annotate doc/lispintro/emacs-lisp-intro.texi @ 99633:9e18920d7076

Fix typo in last change.
author Chong Yidong <cyd@stupidchicken.com>
date Sun, 16 Nov 2008 21:02:22 +0000
parents c9c8b8c7805c
children fe597ddfd2ca
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
83955
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1 \input texinfo @c -*-texinfo-*-
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2 @comment %**start of header
83965
f0912c72f201 (setfilename): Go up one more level.
Glenn Morris <rgm@gnu.org>
parents: 83955
diff changeset
3 @setfilename ../../info/eintr
83955
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4 @c setfilename emacs-lisp-intro.info
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5 @c sethtmlfilename emacs-lisp-intro.html
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6 @settitle Programming in Emacs Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7 @syncodeindex vr cp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8 @syncodeindex fn cp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9 @finalout
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11 @c ---------
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12 @c <<<< For hard copy printing, this file is now
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13 @c set for smallbook, which works for all sizes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14 @c of paper, and with Postscript figures >>>>
98525
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
15 @set smallbook
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
16 @ifset smallbook
83955
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17 @smallbook
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18 @clear largebook
98525
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
19 @end ifset
83955
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20 @set print-postscript-figures
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21 @c set largebook
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22 @c clear print-postscript-figures
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
23 @c ---------
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
24
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
25 @comment %**end of header
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
26
98525
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
27 @c per rms and peterb, use 10pt fonts for the main text, mostly to
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
28 @c save on paper cost.
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
29 @c Do this inside @tex for now, so current makeinfo does not complain.
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
30 @tex
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
31 @ifset smallbook
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
32 @fonttextsize 10
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
33 \global\let\urlcolor=\Black % don't print links in grayscale
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
34 \global\let\linkcolor=\Black
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
35 @end ifset
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
36 \global\hbadness=6666 % don't worry about not-too-underfull boxes
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
37 @end tex
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
38
84513
27b108c35388 Add email address to Thank You
Robert J. Chassell <bob@rattlesnake.com>
parents: 83965
diff changeset
39 @set edition-number 3.08
98525
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
40 @set update-date 4 October 2008
83955
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
41 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
42 ## Summary of shell commands to create various output formats:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
43
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
44 pushd /usr/local/src/emacs/lispintro/
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
45 ## pushd /u/intro/
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
46
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
47 ## Info output
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
48 makeinfo --paragraph-indent=0 --verbose emacs-lisp-intro.texi
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
49
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
50 ## ;; (progn (when (bufferp (get-buffer "*info*")) (kill-buffer "*info*")) (info "/usr/local/src/emacs/info/eintr"))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
51
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
52 ## DVI output
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
53 texi2dvi emacs-lisp-intro.texi
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
54
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
55 ## xdvi -margins 24pt -topmargin 4pt -offsets 24pt -geometry 760x1140 -s 5 -useTeXpages -mousemode 1 emacs-lisp-intro.dvi &
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
56
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
57 ## HTML output
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
58 makeinfo --html --no-split --verbose emacs-lisp-intro.texi
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
59
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
60 ## galeon emacs-lisp-intro.html
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
61
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
62 ## Plain text output
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
63 makeinfo --fill-column=70 --no-split --paragraph-indent=0 \
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
64 --verbose --no-headers --output=emacs-lisp-intro.txt emacs-lisp-intro.texi
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
65
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
66 popd
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
67
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
68 # as user `root'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
69 # insert thumbdrive
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
70 mtusb # mount -v -t ext3 /dev/sda /mnt
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
71 cp -v /u/intro/emacs-lisp-intro.texi /mnt/backup/intro/emacs-lisp-intro.texi
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
72 umtusb # umount -v /mnt
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
73 # remove thumbdrive
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
74
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
75 ## Other shell commands
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
76
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
77 pushd /usr/local/src/emacs/lispintro/
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
78 ## pushd /u/intro/
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
79
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
80 ## PDF
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
81 texi2dvi --pdf emacs-lisp-intro.texi
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
82 # xpdf emacs-lisp-intro.pdf &
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
83
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
84 ## DocBook -- note file extension
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
85 makeinfo --docbook --no-split --paragraph-indent=0 \
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
86 --verbose --output=emacs-lisp-intro.docbook emacs-lisp-intro.texi
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
87
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
88 ## XML with a Texinfo DTD -- note file extension
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
89 makeinfo --xml --no-split --paragraph-indent=0 \
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
90 --verbose --output=emacs-lisp-intro.texinfoxml emacs-lisp-intro.texi
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
91
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
92 ## PostScript (needs DVI)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
93 # gv emacs-lisp-intro.ps &
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
94 # Create DVI if we lack it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
95 # texi2dvi emacs-lisp-intro.texi
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
96 dvips emacs-lisp-intro.dvi -o emacs-lisp-intro.ps
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
97
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
98 ## RTF (needs HTML)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
99 # Use OpenOffice to view RTF
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
100 # Create HTML if we lack it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
101 # makeinfo --no-split --html emacs-lisp-intro.texi
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
102 /usr/local/src/html2rtf.pl emacs-lisp-intro.html
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
103
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
104 ## LaTeX (needs RTF)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
105 /usr/bin/rtf2latex emacs-lisp-intro.rtf
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
106
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
107 popd
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
108
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
109 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
110
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
111 @c ================ Included Figures ================
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
112
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
113 @c Set print-postscript-figures if you print PostScript figures.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
114 @c If you clear this, the ten figures will be printed as ASCII diagrams.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
115 @c (This is not relevant to Info, since Info only handles ASCII.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
116 @c Your site may require editing changes to print PostScript; in this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
117 @c case, search for `print-postscript-figures' and make appropriate changes.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
118
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
119 @c ================ How to Create an Info file ================
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
120
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
121 @c If you have `makeinfo' installed, run the following command
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
122
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
123 @c makeinfo emacs-lisp-intro.texi
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
124
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
125 @c or, if you want a single, large Info file, and no paragraph indents:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
126 @c makeinfo --no-split --paragraph-indent=0 --verbose emacs-lisp-intro.texi
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
127
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
128 @c After creating the Info file, edit your Info `dir' file, if the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
129 @c `dircategory' section below does not enable your system to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
130 @c install the manual automatically.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
131 @c (The `dir' file is often in the `/usr/local/share/info/' directory.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
132
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
133 @c ================ How to Create an HTML file ================
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
134
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
135 @c To convert to HTML format
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
136 @c makeinfo --html --no-split --verbose emacs-lisp-intro.texi
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
137
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
138 @c ================ How to Print a Book in Various Sizes ================
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
139
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
140 @c This book can be printed in any of three different sizes.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
141 @c In the above header, set @-commands appropriately.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
142
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
143 @c 7 by 9.25 inches:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
144 @c @smallbook
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
145 @c @clear largebook
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
146
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
147 @c 8.5 by 11 inches:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
148 @c @c smallbook
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
149 @c @set largebook
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
150
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
151 @c European A4 size paper:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
152 @c @c smallbook
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
153 @c @afourpaper
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
154 @c @set largebook
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
155
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
156 @c ================ How to Typeset and Print ================
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
157
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
158 @c If you do not include PostScript figures, run either of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
159 @c following command sequences, or similar commands suited to your
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
160 @c system:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
161
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
162 @c texi2dvi emacs-lisp-intro.texi
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
163 @c lpr -d emacs-lisp-intro.dvi
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
164
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
165 @c or else:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
166
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
167 @c tex emacs-lisp-intro.texi
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
168 @c texindex emacs-lisp-intro.??
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
169 @c tex emacs-lisp-intro.texi
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
170 @c lpr -d emacs-lisp-intro.dvi
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
171
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
172 @c If you include the PostScript figures, and you have old software,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
173 @c you may need to convert the .dvi file to a .ps file before
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
174 @c printing. Run either of the following command sequences, or one
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
175 @c similar:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
176 @c
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
177 @c dvips -f < emacs-lisp-intro.dvi > emacs-lisp-intro.ps
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
178 @c
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
179 @c or else:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
180 @c
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
181 @c postscript -p < emacs-lisp-intro.dvi > emacs-lisp-intro.ps
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
182 @c
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
183
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
184 @c (Note: if you edit the book so as to change the length of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
185 @c table of contents, you may have to change the value of `pageno' below.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
186
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
187 @c ================ End of Formatting Sections ================
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
188
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
189 @c For next or subsequent edition:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
190 @c create function using with-output-to-temp-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
191 @c create a major mode, with keymaps
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
192 @c run an asynchronous process, like grep or diff
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
193
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
194 @c For 8.5 by 11 inch format: do not use such a small amount of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
195 @c whitespace between paragraphs as smallbook format
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
196 @ifset largebook
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
197 @tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
198 \global\parskip 6pt plus 1pt
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
199 @end tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
200 @end ifset
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
201
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
202 @c For all sized formats: print within-book cross
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
203 @c reference with ``...'' rather than [...]
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
204
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
205 @c This works with the texinfo.tex file, version 2003-05-04.08,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
206 @c in the Texinfo version 4.6 of the 2003 Jun 13 distribution.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
207
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
208 @tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
209 \if \xrefprintnodename
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
210 \global\def\xrefprintnodename#1{\unskip, ``#1''}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
211 \else
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
212 \global\def\xrefprintnodename#1{ ``#1''}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
213 \fi
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
214 % \global\def\xrefprintnodename#1{, ``#1''}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
215 @end tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
216
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
217 @c ----------------------------------------------------
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
218
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
219 @dircategory Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
220 @direntry
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
221 * Emacs Lisp Intro: (eintr).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
222 A simple introduction to Emacs Lisp programming.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
223 @end direntry
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
224
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
225 @copying
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
226 This is an @cite{Introduction to Programming in Emacs Lisp}, for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
227 people who are not programmers.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
228 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
229 Edition @value{edition-number}, @value{update-date}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
230 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
231 Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1997, 2001,
87649
107ccd98fa12 Merge from emacs--rel--22
Miles Bader <miles@gnu.org>
parents: 84515
diff changeset
232 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
83955
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
233 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
234
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
235 @iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
236 Published by the:@*
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
237
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
238 GNU Press, @hfill @uref{http://www.gnupress.org}@*
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
239 a division of the @hfill General: @email{press@@gnu.org}@*
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
240 Free Software Foundation, Inc. @hfill Orders:@w{ } @email{sales@@gnu.org}@*
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
241 51 Franklin Street, Fifth Floor @hfill Tel: +1 (617) 542-5942@*
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
242 Boston, MA 02110-1301 USA @hfill Fax: +1 (617) 542-2652@*
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
243 @end iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
244
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
245 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
246 Published by the:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
247
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
248 @example
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
249 GNU Press, Website: http://www.gnupress.org
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
250 a division of the General: press@@gnu.org
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
251 Free Software Foundation, Inc. Orders: sales@@gnu.org
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
252 51 Franklin Street, Fifth Floor Tel: +1 (617) 542-5942
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
253 Boston, MA 02110-1301 USA Fax: +1 (617) 542-2652
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
254 @end example
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
255 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
256
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
257 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
258 @c Printed copies are available for $30 each.@*
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
259 ISBN 1-882114-43-4
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
260
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
261 Permission is granted to copy, distribute and/or modify this document
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
262 under the terms of the GNU Free Documentation License, Version 1.2 or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
263 any later version published by the Free Software Foundation; there
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
264 being no Invariant Section, with the Front-Cover Texts being ``A GNU
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
265 Manual'', and with the Back-Cover Texts as in (a) below. A copy of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
266 the license is included in the section entitled ``GNU Free
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
267 Documentation License''.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
268
88088
985bbb7a574c emacs-lisp-intro.texi: Update back cover text.
Robert J. Chassell <bob@rattlesnake.com>
parents: 87649
diff changeset
269 (a) The FSF's Back-Cover Text is: ``You have the freedom to
985bbb7a574c emacs-lisp-intro.texi: Update back cover text.
Robert J. Chassell <bob@rattlesnake.com>
parents: 87649
diff changeset
270 copy and modify this GNU manual. Buying copies from the FSF
985bbb7a574c emacs-lisp-intro.texi: Update back cover text.
Robert J. Chassell <bob@rattlesnake.com>
parents: 87649
diff changeset
271 supports it in developing GNU and promoting software freedom.''
83955
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
272 @end copying
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
273
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
274 @c half title; two lines here, so do not use `shorttitlepage'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
275 @tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
276 {\begingroup%
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
277 \hbox{}\vskip 1.5in \chaprm \centerline{An Introduction to}%
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
278 \endgroup}%
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
279 {\begingroup\hbox{}\vskip 0.25in \chaprm%
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
280 \centerline{Programming in Emacs Lisp}%
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
281 \endgroup\page\hbox{}\page}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
282 @end tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
283
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
284 @titlepage
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
285 @sp 6
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
286 @center @titlefont{An Introduction to}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
287 @sp 2
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
288 @center @titlefont{Programming in Emacs Lisp}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
289 @sp 2
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
290 @center Revised Third Edition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
291 @sp 4
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
292 @center by Robert J. Chassell
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
293
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
294 @page
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
295 @vskip 0pt plus 1filll
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
296 @insertcopying
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
297 @end titlepage
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
298
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
299 @iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
300 @headings off
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
301 @evenheading @thispage @| @| @thischapter
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
302 @oddheading @thissection @| @| @thispage
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
303 @end iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
304
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
305 @ifnothtml
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
306 @c Keep T.O.C. short by tightening up for largebook
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
307 @ifset largebook
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
308 @tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
309 \global\parskip 2pt plus 1pt
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
310 \global\advance\baselineskip by -1pt
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
311 @end tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
312 @end ifset
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
313 @end ifnothtml
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
314
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
315 @shortcontents
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
316 @contents
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
317
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
318 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
319 @node Top, Preface, (dir), (dir)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
320 @top An Introduction to Programming in Emacs Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
321
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
322 @insertcopying
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
323
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
324 This master menu first lists each chapter and index; then it lists
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
325 every node in every chapter.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
326 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
327
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
328 @c >>>> Set pageno appropriately <<<<
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
329
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
330 @c The first page of the Preface is a roman numeral; it is the first
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
331 @c right handed page after the Table of Contents; hence the following
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
332 @c setting must be for an odd negative number.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
333
98525
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
334 @c iftex
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
335 @c global@pageno = -11
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
336 @c end iftex
83955
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
337
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
338 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
339 * Preface:: What to look for.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
340 * List Processing:: What is Lisp?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
341 * Practicing Evaluation:: Running several programs.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
342 * Writing Defuns:: How to write function definitions.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
343 * Buffer Walk Through:: Exploring a few buffer-related functions.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
344 * More Complex:: A few, even more complex functions.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
345 * Narrowing & Widening:: Restricting your and Emacs attention to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
346 a region.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
347 * car cdr & cons:: Fundamental functions in Lisp.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
348 * Cutting & Storing Text:: Removing text and saving it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
349 * List Implementation:: How lists are implemented in the computer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
350 * Yanking:: Pasting stored text.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
351 * Loops & Recursion:: How to repeat a process.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
352 * Regexp Search:: Regular expression searches.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
353 * Counting Words:: A review of repetition and regexps.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
354 * Words in a defun:: Counting words in a @code{defun}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
355 * Readying a Graph:: A prototype graph printing function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
356 * Emacs Initialization:: How to write a @file{.emacs} file.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
357 * Debugging:: How to run the Emacs Lisp debuggers.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
358 * Conclusion:: Now you have the basics.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
359 * the-the:: An appendix: how to find reduplicated words.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
360 * Kill Ring:: An appendix: how the kill ring works.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
361 * Full Graph:: How to create a graph with labelled axes.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
362 * Free Software and Free Manuals::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
363 * GNU Free Documentation License::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
364 * Index::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
365 * About the Author::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
366
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
367 @detailmenu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
368 --- The Detailed Node Listing ---
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
369
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
370 Preface
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
371
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
372 * Why:: Why learn Emacs Lisp?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
373 * On Reading this Text:: Read, gain familiarity, pick up habits....
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
374 * Who You Are:: For whom this is written.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
375 * Lisp History::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
376 * Note for Novices:: You can read this as a novice.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
377 * Thank You::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
378
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
379 List Processing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
380
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
381 * Lisp Lists:: What are lists?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
382 * Run a Program:: Any list in Lisp is a program ready to run.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
383 * Making Errors:: Generating an error message.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
384 * Names & Definitions:: Names of symbols and function definitions.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
385 * Lisp Interpreter:: What the Lisp interpreter does.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
386 * Evaluation:: Running a program.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
387 * Variables:: Returning a value from a variable.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
388 * Arguments:: Passing information to a function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
389 * set & setq:: Setting the value of a variable.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
390 * Summary:: The major points.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
391 * Error Message Exercises::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
392
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
393 Lisp Lists
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
394
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
395 * Numbers Lists:: List have numbers, other lists, in them.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
396 * Lisp Atoms:: Elemental entities.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
397 * Whitespace in Lists:: Formatting lists to be readable.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
398 * Typing Lists:: How GNU Emacs helps you type lists.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
399
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
400 The Lisp Interpreter
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
401
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
402 * Complications:: Variables, Special forms, Lists within.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
403 * Byte Compiling:: Specially processing code for speed.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
404
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
405 Evaluation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
406
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
407 * How the Interpreter Acts:: Returns and Side Effects...
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
408 * Evaluating Inner Lists:: Lists within lists...
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
409
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
410 Variables
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
411
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
412 * fill-column Example::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
413 * Void Function:: The error message for a symbol
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
414 without a function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
415 * Void Variable:: The error message for a symbol without a value.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
416
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
417 Arguments
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
418
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
419 * Data types:: Types of data passed to a function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
420 * Args as Variable or List:: An argument can be the value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
421 of a variable or list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
422 * Variable Number of Arguments:: Some functions may take a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
423 variable number of arguments.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
424 * Wrong Type of Argument:: Passing an argument of the wrong type
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
425 to a function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
426 * message:: A useful function for sending messages.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
427
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
428 Setting the Value of a Variable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
429
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
430 * Using set:: Setting values.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
431 * Using setq:: Setting a quoted value.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
432 * Counting:: Using @code{setq} to count.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
433
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
434 Practicing Evaluation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
435
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
436 * How to Evaluate:: Typing editing commands or @kbd{C-x C-e}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
437 causes evaluation.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
438 * Buffer Names:: Buffers and files are different.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
439 * Getting Buffers:: Getting a buffer itself, not merely its name.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
440 * Switching Buffers:: How to change to another buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
441 * Buffer Size & Locations:: Where point is located and the size of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
442 the buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
443 * Evaluation Exercise::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
444
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
445 How To Write Function Definitions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
446
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
447 * Primitive Functions::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
448 * defun:: The @code{defun} special form.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
449 * Install:: Install a function definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
450 * Interactive:: Making a function interactive.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
451 * Interactive Options:: Different options for @code{interactive}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
452 * Permanent Installation:: Installing code permanently.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
453 * let:: Creating and initializing local variables.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
454 * if:: What if?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
455 * else:: If--then--else expressions.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
456 * Truth & Falsehood:: What Lisp considers false and true.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
457 * save-excursion:: Keeping track of point, mark, and buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
458 * Review::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
459 * defun Exercises::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
460
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
461 Install a Function Definition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
462
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
463 * Effect of installation::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
464 * Change a defun:: How to change a function definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
465
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
466 Make a Function Interactive
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
467
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
468 * Interactive multiply-by-seven:: An overview.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
469 * multiply-by-seven in detail:: The interactive version.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
470
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
471 @code{let}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
472
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
473 * Prevent confusion::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
474 * Parts of let Expression::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
475 * Sample let Expression::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
476 * Uninitialized let Variables::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
477
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
478 The @code{if} Special Form
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
479
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
480 * if in more detail::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
481 * type-of-animal in detail:: An example of an @code{if} expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
482
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
483 Truth and Falsehood in Emacs Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
484
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
485 * nil explained:: @code{nil} has two meanings.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
486
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
487 @code{save-excursion}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
488
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
489 * Point and mark:: A review of various locations.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
490 * Template for save-excursion::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
491
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
492 A Few Buffer--Related Functions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
493
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
494 * Finding More:: How to find more information.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
495 * simplified-beginning-of-buffer:: Shows @code{goto-char},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
496 @code{point-min}, and @code{push-mark}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
497 * mark-whole-buffer:: Almost the same as @code{beginning-of-buffer}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
498 * append-to-buffer:: Uses @code{save-excursion} and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
499 @code{insert-buffer-substring}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
500 * Buffer Related Review:: Review.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
501 * Buffer Exercises::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
502
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
503 The Definition of @code{mark-whole-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
504
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
505 * mark-whole-buffer overview::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
506 * Body of mark-whole-buffer:: Only three lines of code.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
507
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
508 The Definition of @code{append-to-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
509
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
510 * append-to-buffer overview::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
511 * append interactive:: A two part interactive expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
512 * append-to-buffer body:: Incorporates a @code{let} expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
513 * append save-excursion:: How the @code{save-excursion} works.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
514
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
515 A Few More Complex Functions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
516
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
517 * copy-to-buffer:: With @code{set-buffer}, @code{get-buffer-create}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
518 * insert-buffer:: Read-only, and with @code{or}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
519 * beginning-of-buffer:: Shows @code{goto-char},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
520 @code{point-min}, and @code{push-mark}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
521 * Second Buffer Related Review::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
522 * optional Exercise::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
523
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
524 The Definition of @code{insert-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
525
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
526 * insert-buffer code::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
527 * insert-buffer interactive:: When you can read, but not write.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
528 * insert-buffer body:: The body has an @code{or} and a @code{let}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
529 * if & or:: Using an @code{if} instead of an @code{or}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
530 * Insert or:: How the @code{or} expression works.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
531 * Insert let:: Two @code{save-excursion} expressions.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
532 * New insert-buffer::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
533
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
534 The Interactive Expression in @code{insert-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
535
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
536 * Read-only buffer:: When a buffer cannot be modified.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
537 * b for interactive:: An existing buffer or else its name.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
538
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
539 Complete Definition of @code{beginning-of-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
540
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
541 * Optional Arguments::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
542 * beginning-of-buffer opt arg:: Example with optional argument.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
543 * beginning-of-buffer complete::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
544
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
545 @code{beginning-of-buffer} with an Argument
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
546
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
547 * Disentangle beginning-of-buffer::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
548 * Large buffer case::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
549 * Small buffer case::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
550
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
551 Narrowing and Widening
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
552
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
553 * Narrowing advantages:: The advantages of narrowing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
554 * save-restriction:: The @code{save-restriction} special form.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
555 * what-line:: The number of the line that point is on.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
556 * narrow Exercise::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
557
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
558 @code{car}, @code{cdr}, @code{cons}: Fundamental Functions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
559
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
560 * Strange Names:: An historical aside: why the strange names?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
561 * car & cdr:: Functions for extracting part of a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
562 * cons:: Constructing a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
563 * nthcdr:: Calling @code{cdr} repeatedly.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
564 * nth::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
565 * setcar:: Changing the first element of a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
566 * setcdr:: Changing the rest of a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
567 * cons Exercise::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
568
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
569 @code{cons}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
570
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
571 * Build a list::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
572 * length:: How to find the length of a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
573
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
574 Cutting and Storing Text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
575
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
576 * Storing Text:: Text is stored in a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
577 * zap-to-char:: Cutting out text up to a character.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
578 * kill-region:: Cutting text out of a region.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
579 * copy-region-as-kill:: A definition for copying text.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
580 * Digression into C:: Minor note on C programming language macros.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
581 * defvar:: How to give a variable an initial value.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
582 * cons & search-fwd Review::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
583 * search Exercises::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
584
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
585 @code{zap-to-char}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
586
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
587 * Complete zap-to-char:: The complete implementation.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
588 * zap-to-char interactive:: A three part interactive expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
589 * zap-to-char body:: A short overview.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
590 * search-forward:: How to search for a string.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
591 * progn:: The @code{progn} special form.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
592 * Summing up zap-to-char:: Using @code{point} and @code{search-forward}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
593
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
594 @code{kill-region}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
595
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
596 * Complete kill-region:: The function definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
597 * condition-case:: Dealing with a problem.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
598 * Lisp macro::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
599
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
600 @code{copy-region-as-kill}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
601
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
602 * Complete copy-region-as-kill:: The complete function definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
603 * copy-region-as-kill body:: The body of @code{copy-region-as-kill}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
604
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
605 The Body of @code{copy-region-as-kill}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
606
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
607 * last-command & this-command::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
608 * kill-append function::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
609 * kill-new function::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
610
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
611 Initializing a Variable with @code{defvar}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
612
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
613 * See variable current value::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
614 * defvar and asterisk::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
615
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
616 How Lists are Implemented
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
617
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
618 * Lists diagrammed::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
619 * Symbols as Chest:: Exploring a powerful metaphor.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
620 * List Exercise::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
621
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
622 Yanking Text Back
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
623
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
624 * Kill Ring Overview::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
625 * kill-ring-yank-pointer:: The kill ring is a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
626 * yank nthcdr Exercises:: The @code{kill-ring-yank-pointer} variable.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
627
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
628 Loops and Recursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
629
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
630 * while:: Causing a stretch of code to repeat.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
631 * dolist dotimes::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
632 * Recursion:: Causing a function to call itself.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
633 * Looping exercise::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
634
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
635 @code{while}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
636
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
637 * Looping with while:: Repeat so long as test returns true.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
638 * Loop Example:: A @code{while} loop that uses a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
639 * print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
640 * Incrementing Loop:: A loop with an incrementing counter.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
641 * Incrementing Loop Details::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
642 * Decrementing Loop:: A loop with a decrementing counter.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
643
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
644 Details of an Incrementing Loop
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
645
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
646 * Incrementing Example:: Counting pebbles in a triangle.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
647 * Inc Example parts:: The parts of the function definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
648 * Inc Example altogether:: Putting the function definition together.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
649
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
650 Loop with a Decrementing Counter
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
651
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
652 * Decrementing Example:: More pebbles on the beach.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
653 * Dec Example parts:: The parts of the function definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
654 * Dec Example altogether:: Putting the function definition together.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
655
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
656 Save your time: @code{dolist} and @code{dotimes}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
657
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
658 * dolist::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
659 * dotimes::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
660
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
661 Recursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
662
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
663 * Building Robots:: Same model, different serial number ...
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
664 * Recursive Definition Parts:: Walk until you stop ...
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
665 * Recursion with list:: Using a list as the test whether to recurse.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
666 * Recursive triangle function::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
667 * Recursion with cond::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
668 * Recursive Patterns:: Often used templates.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
669 * No Deferment:: Don't store up work ...
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
670 * No deferment solution::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
671
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
672 Recursion in Place of a Counter
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
673
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
674 * Recursive Example arg of 1 or 2::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
675 * Recursive Example arg of 3 or 4::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
676
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
677 Recursive Patterns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
678
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
679 * Every::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
680 * Accumulate::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
681 * Keep::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
682
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
683 Regular Expression Searches
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
684
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
685 * sentence-end:: The regular expression for @code{sentence-end}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
686 * re-search-forward:: Very similar to @code{search-forward}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
687 * forward-sentence:: A straightforward example of regexp search.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
688 * forward-paragraph:: A somewhat complex example.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
689 * etags:: How to create your own @file{TAGS} table.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
690 * Regexp Review::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
691 * re-search Exercises::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
692
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
693 @code{forward-sentence}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
694
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
695 * Complete forward-sentence::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
696 * fwd-sentence while loops:: Two @code{while} loops.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
697 * fwd-sentence re-search:: A regular expression search.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
698
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
699 @code{forward-paragraph}: a Goldmine of Functions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
700
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
701 * forward-paragraph in brief:: Key parts of the function definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
702 * fwd-para let:: The @code{let*} expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
703 * fwd-para while:: The forward motion @code{while} loop.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
704
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
705 Counting: Repetition and Regexps
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
706
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
707 * Why Count Words::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
708 * count-words-region:: Use a regexp, but find a problem.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
709 * recursive-count-words:: Start with case of no words in region.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
710 * Counting Exercise::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
711
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
712 The @code{count-words-region} Function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
713
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
714 * Design count-words-region:: The definition using a @code{while} loop.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
715 * Whitespace Bug:: The Whitespace Bug in @code{count-words-region}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
716
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
717 Counting Words in a @code{defun}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
718
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
719 * Divide and Conquer::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
720 * Words and Symbols:: What to count?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
721 * Syntax:: What constitutes a word or symbol?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
722 * count-words-in-defun:: Very like @code{count-words}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
723 * Several defuns:: Counting several defuns in a file.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
724 * Find a File:: Do you want to look at a file?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
725 * lengths-list-file:: A list of the lengths of many definitions.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
726 * Several files:: Counting in definitions in different files.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
727 * Several files recursively:: Recursively counting in different files.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
728 * Prepare the data:: Prepare the data for display in a graph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
729
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
730 Count Words in @code{defuns} in Different Files
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
731
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
732 * lengths-list-many-files:: Return a list of the lengths of defuns.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
733 * append:: Attach one list to another.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
734
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
735 Prepare the Data for Display in a Graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
736
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
737 * Data for Display in Detail::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
738 * Sorting:: Sorting lists.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
739 * Files List:: Making a list of files.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
740 * Counting function definitions::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
741
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
742 Readying a Graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
743
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
744 * Columns of a graph::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
745 * graph-body-print:: How to print the body of a graph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
746 * recursive-graph-body-print::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
747 * Printed Axes::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
748 * Line Graph Exercise::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
749
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
750 Your @file{.emacs} File
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
751
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
752 * Default Configuration::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
753 * Site-wide Init:: You can write site-wide init files.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
754 * defcustom:: Emacs will write code for you.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
755 * Beginning a .emacs File:: How to write a @code{.emacs file}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
756 * Text and Auto-fill:: Automatically wrap lines.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
757 * Mail Aliases:: Use abbreviations for email addresses.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
758 * Indent Tabs Mode:: Don't use tabs with @TeX{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
759 * Keybindings:: Create some personal keybindings.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
760 * Keymaps:: More about key binding.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
761 * Loading Files:: Load (i.e., evaluate) files automatically.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
762 * Autoload:: Make functions available.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
763 * Simple Extension:: Define a function; bind it to a key.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
764 * X11 Colors:: Colors in X.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
765 * Miscellaneous::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
766 * Mode Line:: How to customize your mode line.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
767
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
768 Debugging
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
769
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
770 * debug:: How to use the built-in debugger.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
771 * debug-on-entry:: Start debugging when you call a function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
772 * debug-on-quit:: Start debugging when you quit with @kbd{C-g}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
773 * edebug:: How to use Edebug, a source level debugger.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
774 * Debugging Exercises::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
775
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
776 Handling the Kill Ring
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
777
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
778 * What the Kill Ring Does::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
779 * current-kill::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
780 * yank:: Paste a copy of a clipped element.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
781 * yank-pop:: Insert element pointed to.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
782 * ring file::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
783
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
784 The @code{current-kill} Function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
785
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
786 * Understanding current-kill::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
787
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
788 @code{current-kill} in Outline
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
789
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
790 * Body of current-kill::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
791 * Digression concerning error:: How to mislead humans, but not computers.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
792 * Determining the Element::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
793
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
794 A Graph with Labelled Axes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
795
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
796 * Labelled Example::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
797 * print-graph Varlist:: @code{let} expression in @code{print-graph}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
798 * print-Y-axis:: Print a label for the vertical axis.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
799 * print-X-axis:: Print a horizontal label.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
800 * Print Whole Graph:: The function to print a complete graph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
801
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
802 The @code{print-Y-axis} Function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
803
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
804 * print-Y-axis in Detail::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
805 * Height of label:: What height for the Y axis?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
806 * Compute a Remainder:: How to compute the remainder of a division.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
807 * Y Axis Element:: Construct a line for the Y axis.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
808 * Y-axis-column:: Generate a list of Y axis labels.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
809 * print-Y-axis Penultimate:: A not quite final version.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
810
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
811 The @code{print-X-axis} Function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
812
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
813 * Similarities differences:: Much like @code{print-Y-axis}, but not exactly.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
814 * X Axis Tic Marks:: Create tic marks for the horizontal axis.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
815
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
816 Printing the Whole Graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
817
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
818 * The final version:: A few changes.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
819 * Test print-graph:: Run a short test.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
820 * Graphing words in defuns:: Executing the final code.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
821 * lambda:: How to write an anonymous function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
822 * mapcar:: Apply a function to elements of a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
823 * Another Bug:: Yet another bug @dots{} most insidious.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
824 * Final printed graph:: The graph itself!
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
825
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
826 @end detailmenu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
827 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
828
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
829 @node Preface, List Processing, Top, Top
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
830 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
831 @unnumbered Preface
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
832
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
833 Most of the GNU Emacs integrated environment is written in the programming
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
834 language called Emacs Lisp. The code written in this programming
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
835 language is the software---the sets of instructions---that tell the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
836 computer what to do when you give it commands. Emacs is designed so
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
837 that you can write new code in Emacs Lisp and easily install it as an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
838 extension to the editor.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
839
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
840 (GNU Emacs is sometimes called an ``extensible editor'', but it does
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
841 much more than provide editing capabilities. It is better to refer to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
842 Emacs as an ``extensible computing environment''. However, that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
843 phrase is quite a mouthful. It is easier to refer to Emacs simply as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
844 an editor. Moreover, everything you do in Emacs---find the Mayan date
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
845 and phases of the moon, simplify polynomials, debug code, manage
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
846 files, read letters, write books---all these activities are kinds of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
847 editing in the most general sense of the word.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
848
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
849 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
850 * Why:: Why learn Emacs Lisp?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
851 * On Reading this Text:: Read, gain familiarity, pick up habits....
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
852 * Who You Are:: For whom this is written.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
853 * Lisp History::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
854 * Note for Novices:: You can read this as a novice.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
855 * Thank You::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
856 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
857
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
858 @node Why, On Reading this Text, Preface, Preface
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
859 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
860 @unnumberedsec Why Study Emacs Lisp?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
861 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
862
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
863 Although Emacs Lisp is usually thought of in association only with Emacs,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
864 it is a full computer programming language. You can use Emacs Lisp as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
865 you would any other programming language.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
866
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
867 Perhaps you want to understand programming; perhaps you want to extend
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
868 Emacs; or perhaps you want to become a programmer. This introduction to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
869 Emacs Lisp is designed to get you started: to guide you in learning the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
870 fundamentals of programming, and more importantly, to show you how you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
871 can teach yourself to go further.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
872
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
873 @node On Reading this Text, Who You Are, Why, Preface
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
874 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
875 @unnumberedsec On Reading this Text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
876
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
877 All through this document, you will see little sample programs you can
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
878 run inside of Emacs. If you read this document in Info inside of GNU
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
879 Emacs, you can run the programs as they appear. (This is easy to do and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
880 is explained when the examples are presented.) Alternatively, you can
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
881 read this introduction as a printed book while sitting beside a computer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
882 running Emacs. (This is what I like to do; I like printed books.) If
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
883 you don't have a running Emacs beside you, you can still read this book,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
884 but in this case, it is best to treat it as a novel or as a travel guide
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
885 to a country not yet visited: interesting, but not the same as being
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
886 there.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
887
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
888 Much of this introduction is dedicated to walk-throughs or guided tours
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
889 of code used in GNU Emacs. These tours are designed for two purposes:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
890 first, to give you familiarity with real, working code (code you use
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
891 every day); and, second, to give you familiarity with the way Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
892 works. It is interesting to see how a working environment is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
893 implemented.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
894 Also, I
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
895 hope that you will pick up the habit of browsing through source code.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
896 You can learn from it and mine it for ideas. Having GNU Emacs is like
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
897 having a dragon's cave of treasures.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
898
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
899 In addition to learning about Emacs as an editor and Emacs Lisp as a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
900 programming language, the examples and guided tours will give you an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
901 opportunity to get acquainted with Emacs as a Lisp programming
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
902 environment. GNU Emacs supports programming and provides tools that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
903 you will want to become comfortable using, such as @kbd{M-.} (the key
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
904 which invokes the @code{find-tag} command). You will also learn about
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
905 buffers and other objects that are part of the environment.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
906 Learning about these features of Emacs is like learning new routes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
907 around your home town.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
908
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
909 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
910 In addition, I have written several programs as extended examples.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
911 Although these are examples, the programs are real. I use them.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
912 Other people use them. You may use them. Beyond the fragments of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
913 programs used for illustrations, there is very little in here that is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
914 `just for teaching purposes'; what you see is used. This is a great
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
915 advantage of Emacs Lisp: it is easy to learn to use it for work.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
916 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
917
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
918 Finally, I hope to convey some of the skills for using Emacs to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
919 learn aspects of programming that you don't know. You can often use
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
920 Emacs to help you understand what puzzles you or to find out how to do
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
921 something new. This self-reliance is not only a pleasure, but an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
922 advantage.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
923
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
924 @node Who You Are, Lisp History, On Reading this Text, Preface
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
925 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
926 @unnumberedsec For Whom This is Written
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
927
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
928 This text is written as an elementary introduction for people who are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
929 not programmers. If you are a programmer, you may not be satisfied with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
930 this primer. The reason is that you may have become expert at reading
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
931 reference manuals and be put off by the way this text is organized.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
932
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
933 An expert programmer who reviewed this text said to me:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
934
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
935 @quotation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
936 @i{I prefer to learn from reference manuals. I ``dive into'' each
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
937 paragraph, and ``come up for air'' between paragraphs.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
938
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
939 @i{When I get to the end of a paragraph, I assume that that subject is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
940 done, finished, that I know everything I need (with the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
941 possible exception of the case when the next paragraph starts talking
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
942 about it in more detail). I expect that a well written reference manual
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
943 will not have a lot of redundancy, and that it will have excellent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
944 pointers to the (one) place where the information I want is.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
945 @end quotation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
946
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
947 This introduction is not written for this person!
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
948
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
949 Firstly, I try to say everything at least three times: first, to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
950 introduce it; second, to show it in context; and third, to show it in a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
951 different context, or to review it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
952
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
953 Secondly, I hardly ever put all the information about a subject in one
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
954 place, much less in one paragraph. To my way of thinking, that imposes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
955 too heavy a burden on the reader. Instead I try to explain only what
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
956 you need to know at the time. (Sometimes I include a little extra
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
957 information so you won't be surprised later when the additional
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
958 information is formally introduced.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
959
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
960 When you read this text, you are not expected to learn everything the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
961 first time. Frequently, you need only make, as it were, a `nodding
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
962 acquaintance' with some of the items mentioned. My hope is that I have
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
963 structured the text and given you enough hints that you will be alert to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
964 what is important, and concentrate on it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
965
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
966 You will need to ``dive into'' some paragraphs; there is no other way
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
967 to read them. But I have tried to keep down the number of such
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
968 paragraphs. This book is intended as an approachable hill, rather than
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
969 as a daunting mountain.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
970
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
971 This introduction to @cite{Programming in Emacs Lisp} has a companion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
972 document,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
973 @iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
974 @cite{The GNU Emacs Lisp Reference Manual}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
975 @end iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
976 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
977 @ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
978 Emacs Lisp Reference Manual}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
979 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
980 The reference manual has more detail than this introduction. In the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
981 reference manual, all the information about one topic is concentrated
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
982 in one place. You should turn to it if you are like the programmer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
983 quoted above. And, of course, after you have read this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
984 @cite{Introduction}, you will find the @cite{Reference Manual} useful
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
985 when you are writing your own programs.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
986
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
987 @node Lisp History, Note for Novices, Who You Are, Preface
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
988 @unnumberedsec Lisp History
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
989 @cindex Lisp history
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
990
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
991 Lisp was first developed in the late 1950s at the Massachusetts
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
992 Institute of Technology for research in artificial intelligence. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
993 great power of the Lisp language makes it superior for other purposes as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
994 well, such as writing editor commands and integrated environments.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
995
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
996 @cindex Maclisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
997 @cindex Common Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
998 GNU Emacs Lisp is largely inspired by Maclisp, which was written at MIT
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
999 in the 1960s. It is somewhat inspired by Common Lisp, which became a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1000 standard in the 1980s. However, Emacs Lisp is much simpler than Common
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1001 Lisp. (The standard Emacs distribution contains an optional extensions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1002 file, @file{cl.el}, that adds many Common Lisp features to Emacs Lisp.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1003
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1004 @node Note for Novices, Thank You, Lisp History, Preface
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1005 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1006 @unnumberedsec A Note for Novices
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1007
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1008 If you don't know GNU Emacs, you can still read this document
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1009 profitably. However, I recommend you learn Emacs, if only to learn to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1010 move around your computer screen. You can teach yourself how to use
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1011 Emacs with the on-line tutorial. To use it, type @kbd{C-h t}. (This
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1012 means you press and release the @key{CTRL} key and the @kbd{h} at the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1013 same time, and then press and release @kbd{t}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1014
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1015 Also, I often refer to one of Emacs' standard commands by listing the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1016 keys which you press to invoke the command and then giving the name of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1017 the command in parentheses, like this: @kbd{M-C-\}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1018 (@code{indent-region}). What this means is that the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1019 @code{indent-region} command is customarily invoked by typing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1020 @kbd{M-C-\}. (You can, if you wish, change the keys that are typed to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1021 invoke the command; this is called @dfn{rebinding}. @xref{Keymaps, ,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1022 Keymaps}.) The abbreviation @kbd{M-C-\} means that you type your
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1023 @key{META} key, @key{CTRL} key and @key{\} key all at the same time.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1024 (On many modern keyboards the @key{META} key is labelled
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1025 @key{ALT}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1026 Sometimes a combination like this is called a keychord, since it is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1027 similar to the way you play a chord on a piano. If your keyboard does
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1028 not have a @key{META} key, the @key{ESC} key prefix is used in place
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1029 of it. In this case, @kbd{M-C-\} means that you press and release your
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1030 @key{ESC} key and then type the @key{CTRL} key and the @key{\} key at
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1031 the same time. But usually @kbd{M-C-\} means press the @key{CTRL} key
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1032 along with the key that is labelled @key{ALT} and, at the same time,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1033 press the @key{\} key.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1034
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1035 In addition to typing a lone keychord, you can prefix what you type
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1036 with @kbd{C-u}, which is called the `universal argument'. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1037 @kbd{C-u} keychord passes an argument to the subsequent command.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1038 Thus, to indent a region of plain text by 6 spaces, mark the region,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1039 and then type @w{@kbd{C-u 6 M-C-\}}. (If you do not specify a number,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1040 Emacs either passes the number 4 to the command or otherwise runs the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1041 command differently than it would otherwise.) @xref{Arguments, ,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1042 Numeric Arguments, emacs, The GNU Emacs Manual}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1043
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1044 If you are reading this in Info using GNU Emacs, you can read through
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1045 this whole document just by pressing the space bar, @key{SPC}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1046 (To learn about Info, type @kbd{C-h i} and then select Info.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1047
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1048 A note on terminology: when I use the word Lisp alone, I often am
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1049 referring to the various dialects of Lisp in general, but when I speak
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1050 of Emacs Lisp, I am referring to GNU Emacs Lisp in particular.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1051
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1052 @node Thank You, , Note for Novices, Preface
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1053 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1054 @unnumberedsec Thank You
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1055
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1056 My thanks to all who helped me with this book. My especial thanks to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1057 @r{Jim Blandy}, @r{Noah Friedman}, @w{Jim Kingdon}, @r{Roland
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1058 McGrath}, @w{Frank Ritter}, @w{Randy Smith}, @w{Richard M.@:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1059 Stallman}, and @w{Melissa Weisshaus}. My thanks also go to both
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1060 @w{Philip Johnson} and @w{David Stampe} for their patient
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1061 encouragement. My mistakes are my own.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1062
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1063 @flushright
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1064 Robert J. Chassell
84515
6979ff5651fe Add email address to Thank You correctly
Robert J. Chassell <bob@rattlesnake.com>
parents: 84513
diff changeset
1065 @email{bob@@gnu.org}
83955
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1066 @end flushright
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1067
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1068 @c ================ Beginning of main text ================
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1069
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1070 @c Start main text on right-hand (verso) page
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1071
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1072 @tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1073 \par\vfill\supereject
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1074 \headings off
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1075 \ifodd\pageno
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1076 \par\vfill\supereject
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1077 \else
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1078 \par\vfill\supereject
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1079 \page\hbox{}\page
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1080 \par\vfill\supereject
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1081 \fi
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1082 @end tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1083
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1084 @iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1085 @headings off
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1086 @evenheading @thispage @| @| @thischapter
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1087 @oddheading @thissection @| @| @thispage
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1088 @global@pageno = 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1089 @end iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1090
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1091 @node List Processing, Practicing Evaluation, Preface, Top
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1092 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1093 @chapter List Processing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1094
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1095 To the untutored eye, Lisp is a strange programming language. In Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1096 code there are parentheses everywhere. Some people even claim that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1097 the name stands for `Lots of Isolated Silly Parentheses'. But the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1098 claim is unwarranted. Lisp stands for LISt Processing, and the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1099 programming language handles @emph{lists} (and lists of lists) by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1100 putting them between parentheses. The parentheses mark the boundaries
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1101 of the list. Sometimes a list is preceded by a single apostrophe or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1102 quotation mark, @samp{'}@footnote{The single apostrophe or quotation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1103 mark is an abbreviation for the function @code{quote}; you need not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1104 think about functions now; functions are defined in @ref{Making
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1105 Errors, , Generate an Error Message}.} Lists are the basis of Lisp.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1106
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1107 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1108 * Lisp Lists:: What are lists?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1109 * Run a Program:: Any list in Lisp is a program ready to run.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1110 * Making Errors:: Generating an error message.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1111 * Names & Definitions:: Names of symbols and function definitions.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1112 * Lisp Interpreter:: What the Lisp interpreter does.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1113 * Evaluation:: Running a program.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1114 * Variables:: Returning a value from a variable.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1115 * Arguments:: Passing information to a function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1116 * set & setq:: Setting the value of a variable.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1117 * Summary:: The major points.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1118 * Error Message Exercises::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1119 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1120
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1121 @node Lisp Lists, Run a Program, List Processing, List Processing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1122 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1123 @section Lisp Lists
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1124 @cindex Lisp Lists
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1125
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1126 In Lisp, a list looks like this: @code{'(rose violet daisy buttercup)}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1127 This list is preceded by a single apostrophe. It could just as well be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1128 written as follows, which looks more like the kind of list you are likely
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1129 to be familiar with:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1130
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1131 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1132 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1133 '(rose
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1134 violet
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1135 daisy
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1136 buttercup)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1137 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1138 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1139
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1140 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1141 The elements of this list are the names of the four different flowers,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1142 separated from each other by whitespace and surrounded by parentheses,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1143 like flowers in a field with a stone wall around them.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1144 @cindex Flowers in a field
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1145
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1146 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1147 * Numbers Lists:: List have numbers, other lists, in them.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1148 * Lisp Atoms:: Elemental entities.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1149 * Whitespace in Lists:: Formatting lists to be readable.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1150 * Typing Lists:: How GNU Emacs helps you type lists.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1151 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1152
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1153 @node Numbers Lists, Lisp Atoms, Lisp Lists, Lisp Lists
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1154 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1155 @unnumberedsubsec Numbers, Lists inside of Lists
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1156 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1157
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1158 Lists can also have numbers in them, as in this list: @code{(+ 2 2)}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1159 This list has a plus-sign, @samp{+}, followed by two @samp{2}s, each
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1160 separated by whitespace.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1161
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1162 In Lisp, both data and programs are represented the same way; that is,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1163 they are both lists of words, numbers, or other lists, separated by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1164 whitespace and surrounded by parentheses. (Since a program looks like
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1165 data, one program may easily serve as data for another; this is a very
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1166 powerful feature of Lisp.) (Incidentally, these two parenthetical
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1167 remarks are @emph{not} Lisp lists, because they contain @samp{;} and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1168 @samp{.} as punctuation marks.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1169
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1170 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1171 Here is another list, this time with a list inside of it:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1172
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1173 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1174 '(this list has (a list inside of it))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1175 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1176
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1177 The components of this list are the words @samp{this}, @samp{list},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1178 @samp{has}, and the list @samp{(a list inside of it)}. The interior
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1179 list is made up of the words @samp{a}, @samp{list}, @samp{inside},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1180 @samp{of}, @samp{it}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1181
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1182 @node Lisp Atoms, Whitespace in Lists, Numbers Lists, Lisp Lists
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1183 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1184 @subsection Lisp Atoms
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1185 @cindex Lisp Atoms
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1186
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1187 In Lisp, what we have been calling words are called @dfn{atoms}. This
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1188 term comes from the historical meaning of the word atom, which means
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1189 `indivisible'. As far as Lisp is concerned, the words we have been
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1190 using in the lists cannot be divided into any smaller parts and still
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1191 mean the same thing as part of a program; likewise with numbers and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1192 single character symbols like @samp{+}. On the other hand, unlike an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1193 ancient atom, a list can be split into parts. (@xref{car cdr & cons,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1194 , @code{car} @code{cdr} & @code{cons} Fundamental Functions}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1195
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1196 In a list, atoms are separated from each other by whitespace. They can be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1197 right next to a parenthesis.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1198
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1199 @cindex @samp{empty list} defined
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1200 Technically speaking, a list in Lisp consists of parentheses surrounding
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1201 atoms separated by whitespace or surrounding other lists or surrounding
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1202 both atoms and other lists. A list can have just one atom in it or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1203 have nothing in it at all. A list with nothing in it looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1204 @code{()}, and is called the @dfn{empty list}. Unlike anything else, an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1205 empty list is considered both an atom and a list at the same time.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1206
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1207 @cindex Symbolic expressions, introduced
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1208 @cindex @samp{expression} defined
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1209 @cindex @samp{form} defined
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1210 The printed representation of both atoms and lists are called
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1211 @dfn{symbolic expressions} or, more concisely, @dfn{s-expressions}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1212 The word @dfn{expression} by itself can refer to either the printed
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1213 representation, or to the atom or list as it is held internally in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1214 computer. Often, people use the term @dfn{expression}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1215 indiscriminately. (Also, in many texts, the word @dfn{form} is used
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1216 as a synonym for expression.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1217
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1218 Incidentally, the atoms that make up our universe were named such when
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1219 they were thought to be indivisible; but it has been found that physical
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1220 atoms are not indivisible. Parts can split off an atom or it can
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1221 fission into two parts of roughly equal size. Physical atoms were named
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1222 prematurely, before their truer nature was found. In Lisp, certain
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1223 kinds of atom, such as an array, can be separated into parts; but the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1224 mechanism for doing this is different from the mechanism for splitting a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1225 list. As far as list operations are concerned, the atoms of a list are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1226 unsplittable.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1227
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1228 As in English, the meanings of the component letters of a Lisp atom
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1229 are different from the meaning the letters make as a word. For
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1230 example, the word for the South American sloth, the @samp{ai}, is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1231 completely different from the two words, @samp{a}, and @samp{i}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1232
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1233 There are many kinds of atom in nature but only a few in Lisp: for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1234 example, @dfn{numbers}, such as 37, 511, or 1729, and @dfn{symbols}, such
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1235 as @samp{+}, @samp{foo}, or @samp{forward-line}. The words we have
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1236 listed in the examples above are all symbols. In everyday Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1237 conversation, the word ``atom'' is not often used, because programmers
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1238 usually try to be more specific about what kind of atom they are dealing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1239 with. Lisp programming is mostly about symbols (and sometimes numbers)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1240 within lists. (Incidentally, the preceding three word parenthetical
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1241 remark is a proper list in Lisp, since it consists of atoms, which in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1242 this case are symbols, separated by whitespace and enclosed by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1243 parentheses, without any non-Lisp punctuation.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1244
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1245 @need 1250
94896
3c3a05682534 (Lisp Atoms): Rephrase "in addition" to avoid confusion with addition
Chong Yidong <cyd@stupidchicken.com>
parents: 94188
diff changeset
1246 Text between double quotation marks---even sentences or
3c3a05682534 (Lisp Atoms): Rephrase "in addition" to avoid confusion with addition
Chong Yidong <cyd@stupidchicken.com>
parents: 94188
diff changeset
1247 paragraphs---is also an atom. Here is an example:
83955
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1248 @cindex Text between double quotation marks
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1249
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1250 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1251 '(this list includes "text between quotation marks.")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1252 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1253
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1254 @cindex @samp{string} defined
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1255 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1256 In Lisp, all of the quoted text including the punctuation mark and the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1257 blank spaces is a single atom. This kind of atom is called a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1258 @dfn{string} (for `string of characters') and is the sort of thing that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1259 is used for messages that a computer can print for a human to read.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1260 Strings are a different kind of atom than numbers or symbols and are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1261 used differently.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1262
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1263 @node Whitespace in Lists, Typing Lists, Lisp Atoms, Lisp Lists
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1264 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1265 @subsection Whitespace in Lists
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1266 @cindex Whitespace in lists
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1267
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1268 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1269 The amount of whitespace in a list does not matter. From the point of view
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1270 of the Lisp language,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1271
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1272 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1273 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1274 '(this list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1275 looks like this)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1276 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1277 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1278
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1279 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1280 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1281 is exactly the same as this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1282
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1283 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1284 '(this list looks like this)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1285 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1286
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1287 Both examples show what to Lisp is the same list, the list made up of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1288 the symbols @samp{this}, @samp{list}, @samp{looks}, @samp{like}, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1289 @samp{this} in that order.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1290
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1291 Extra whitespace and newlines are designed to make a list more readable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1292 by humans. When Lisp reads the expression, it gets rid of all the extra
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1293 whitespace (but it needs to have at least one space between atoms in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1294 order to tell them apart.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1295
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1296 Odd as it seems, the examples we have seen cover almost all of what Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1297 lists look like! Every other list in Lisp looks more or less like one
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1298 of these examples, except that the list may be longer and more complex.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1299 In brief, a list is between parentheses, a string is between quotation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1300 marks, a symbol looks like a word, and a number looks like a number.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1301 (For certain situations, square brackets, dots and a few other special
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1302 characters may be used; however, we will go quite far without them.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1303
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1304 @node Typing Lists, , Whitespace in Lists, Lisp Lists
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1305 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1306 @subsection GNU Emacs Helps You Type Lists
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1307 @cindex Help typing lists
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1308 @cindex Formatting help
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1309
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1310 When you type a Lisp expression in GNU Emacs using either Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1311 Interaction mode or Emacs Lisp mode, you have available to you several
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1312 commands to format the Lisp expression so it is easy to read. For
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1313 example, pressing the @key{TAB} key automatically indents the line the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1314 cursor is on by the right amount. A command to properly indent the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1315 code in a region is customarily bound to @kbd{M-C-\}. Indentation is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1316 designed so that you can see which elements of a list belong to which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1317 list---elements of a sub-list are indented more than the elements of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1318 the enclosing list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1319
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1320 In addition, when you type a closing parenthesis, Emacs momentarily
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1321 jumps the cursor back to the matching opening parenthesis, so you can
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1322 see which one it is. This is very useful, since every list you type
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1323 in Lisp must have its closing parenthesis match its opening
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1324 parenthesis. (@xref{Major Modes, , Major Modes, emacs, The GNU Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1325 Manual}, for more information about Emacs' modes.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1326
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1327 @node Run a Program, Making Errors, Lisp Lists, List Processing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1328 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1329 @section Run a Program
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1330 @cindex Run a program
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1331 @cindex Program, running one
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1332
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1333 @cindex @samp{evaluate} defined
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1334 A list in Lisp---any list---is a program ready to run. If you run it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1335 (for which the Lisp jargon is @dfn{evaluate}), the computer will do one
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1336 of three things: do nothing except return to you the list itself; send
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1337 you an error message; or, treat the first symbol in the list as a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1338 command to do something. (Usually, of course, it is the last of these
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1339 three things that you really want!)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1340
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1341 @c use code for the single apostrophe, not samp.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1342 The single apostrophe, @code{'}, that I put in front of some of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1343 example lists in preceding sections is called a @dfn{quote}; when it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1344 precedes a list, it tells Lisp to do nothing with the list, other than
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1345 take it as it is written. But if there is no quote preceding a list,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1346 the first item of the list is special: it is a command for the computer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1347 to obey. (In Lisp, these commands are called @emph{functions}.) The list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1348 @code{(+ 2 2)} shown above did not have a quote in front of it, so Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1349 understands that the @code{+} is an instruction to do something with the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1350 rest of the list: add the numbers that follow.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1351
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1352 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1353 If you are reading this inside of GNU Emacs in Info, here is how you can
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1354 evaluate such a list: place your cursor immediately after the right
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1355 hand parenthesis of the following list and then type @kbd{C-x C-e}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1356
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1357 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1358 (+ 2 2)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1359 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1360
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1361 @c use code for the number four, not samp.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1362 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1363 You will see the number @code{4} appear in the echo area. (In the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1364 jargon, what you have just done is ``evaluate the list.'' The echo area
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1365 is the line at the bottom of the screen that displays or ``echoes''
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1366 text.) Now try the same thing with a quoted list: place the cursor
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1367 right after the following list and type @kbd{C-x C-e}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1368
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1369 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1370 '(this is a quoted list)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1371 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1372
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1373 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1374 You will see @code{(this is a quoted list)} appear in the echo area.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1375
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1376 @cindex Lisp interpreter, explained
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1377 @cindex Interpreter, Lisp, explained
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1378 In both cases, what you are doing is giving a command to the program
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1379 inside of GNU Emacs called the @dfn{Lisp interpreter}---giving the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1380 interpreter a command to evaluate the expression. The name of the Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1381 interpreter comes from the word for the task done by a human who comes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1382 up with the meaning of an expression---who ``interprets'' it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1383
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1384 You can also evaluate an atom that is not part of a list---one that is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1385 not surrounded by parentheses; again, the Lisp interpreter translates
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1386 from the humanly readable expression to the language of the computer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1387 But before discussing this (@pxref{Variables}), we will discuss what the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1388 Lisp interpreter does when you make an error.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1389
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1390 @node Making Errors, Names & Definitions, Run a Program, List Processing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1391 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1392 @section Generate an Error Message
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1393 @cindex Generate an error message
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1394 @cindex Error message generation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1395
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1396 Partly so you won't worry if you do it accidentally, we will now give
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1397 a command to the Lisp interpreter that generates an error message.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1398 This is a harmless activity; and indeed, we will often try to generate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1399 error messages intentionally. Once you understand the jargon, error
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1400 messages can be informative. Instead of being called ``error''
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1401 messages, they should be called ``help'' messages. They are like
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1402 signposts to a traveller in a strange country; deciphering them can be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1403 hard, but once understood, they can point the way.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1404
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1405 The error message is generated by a built-in GNU Emacs debugger. We
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1406 will `enter the debugger'. You get out of the debugger by typing @code{q}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1407
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1408 What we will do is evaluate a list that is not quoted and does not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1409 have a meaningful command as its first element. Here is a list almost
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1410 exactly the same as the one we just used, but without the single-quote
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1411 in front of it. Position the cursor right after it and type @kbd{C-x
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1412 C-e}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1413
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1414 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1415 (this is an unquoted list)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1416 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1417
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1418 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1419 What you see depends on which version of Emacs you are running. GNU
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1420 Emacs version 22 provides more information than version 20 and before.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1421 First, the more recent result of generating an error; then the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1422 earlier, version 20 result.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1423
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1424 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1425 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1426 In GNU Emacs version 22, a @file{*Backtrace*} window will open up and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1427 you will see the following in it:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1428
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1429 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1430 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1431 ---------- Buffer: *Backtrace* ----------
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1432 Debugger entered--Lisp error: (void-function this)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1433 (this is an unquoted list)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1434 eval((this is an unquoted list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1435 eval-last-sexp-1(nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1436 eval-last-sexp(nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1437 call-interactively(eval-last-sexp)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1438 ---------- Buffer: *Backtrace* ----------
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1439 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1440 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1441
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1442 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1443 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1444 Your cursor will be in this window (you may have to wait a few seconds
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1445 before it becomes visible). To quit the debugger and make the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1446 debugger window go away, type:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1447
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1448 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1449 q
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1450 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1451
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1452 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1453 Please type @kbd{q} right now, so you become confident that you can
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1454 get out of the debugger. Then, type @kbd{C-x C-e} again to re-enter
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1455 it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1456
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1457 @cindex @samp{function} defined
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1458 Based on what we already know, we can almost read this error message.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1459
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1460 You read the @file{*Backtrace*} buffer from the bottom up; it tells
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1461 you what Emacs did. When you typed @kbd{C-x C-e}, you made an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1462 interactive call to the command @code{eval-last-sexp}. @code{eval} is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1463 an abbreviation for `evaluate' and @code{sexp} is an abbreviation for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1464 `symbolic expression'. The command means `evaluate last symbolic
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1465 expression', which is the expression just before your cursor.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1466
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1467 Each line above tells you what the Lisp interpreter evaluated next.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1468 The most recent action is at the top. The buffer is called the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1469 @file{*Backtrace*} buffer because it enables you to track Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1470 backwards.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1471
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1472 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1473 At the top of the @file{*Backtrace*} buffer, you see the line:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1474
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1475 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1476 Debugger entered--Lisp error: (void-function this)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1477 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1478
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1479 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1480 The Lisp interpreter tried to evaluate the first atom of the list, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1481 word @samp{this}. It is this action that generated the error message
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1482 @samp{void-function this}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1483
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1484 The message contains the words @samp{void-function} and @samp{this}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1485
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1486 @cindex @samp{function} defined
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1487 The word @samp{function} was mentioned once before. It is a very
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1488 important word. For our purposes, we can define it by saying that a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1489 @dfn{function} is a set of instructions to the computer that tell the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1490 computer to do something.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1491
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1492 Now we can begin to understand the error message: @samp{void-function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1493 this}. The function (that is, the word @samp{this}) does not have a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1494 definition of any set of instructions for the computer to carry out.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1495
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1496 The slightly odd word, @samp{void-function}, is designed to cover the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1497 way Emacs Lisp is implemented, which is that when a symbol does not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1498 have a function definition attached to it, the place that should
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1499 contain the instructions is `void'.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1501 On the other hand, since we were able to add 2 plus 2 successfully, by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1502 evaluating @code{(+ 2 2)}, we can infer that the symbol @code{+} must
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1503 have a set of instructions for the computer to obey and those
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1504 instructions must be to add the numbers that follow the @code{+}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1505
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1506 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1507 In GNU Emacs version 20, and in earlier versions, you will see only
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1508 one line of error message; it will appear in the echo area and look
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1509 like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1510
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1511 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1512 Symbol's function definition is void:@: this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1513 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1514
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1515 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1516 (Also, your terminal may beep at you---some do, some don't; and others
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1517 blink. This is just a device to get your attention.) The message goes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1518 away as soon as you type another key, even just to move the cursor.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1519
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1520 We know the meaning of the word @samp{Symbol}. It refers to the first
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1521 atom of the list, the word @samp{this}. The word @samp{function}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1522 refers to the instructions that tell the computer what to do.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1523 (Technically, the symbol tells the computer where to find the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1524 instructions, but this is a complication we can ignore for the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1525 moment.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1526
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1527 The error message can be understood: @samp{Symbol's function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1528 definition is void:@: this}. The symbol (that is, the word
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1529 @samp{this}) lacks instructions for the computer to carry out.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1530
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1531 @node Names & Definitions, Lisp Interpreter, Making Errors, List Processing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1532 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1533 @section Symbol Names and Function Definitions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1534 @cindex Symbol names
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1535
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1536 We can articulate another characteristic of Lisp based on what we have
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1537 discussed so far---an important characteristic: a symbol, like
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1538 @code{+}, is not itself the set of instructions for the computer to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1539 carry out. Instead, the symbol is used, perhaps temporarily, as a way
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1540 of locating the definition or set of instructions. What we see is the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1541 name through which the instructions can be found. Names of people
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1542 work the same way. I can be referred to as @samp{Bob}; however, I am
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1543 not the letters @samp{B}, @samp{o}, @samp{b} but am, or was, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1544 consciousness consistently associated with a particular life-form.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1545 The name is not me, but it can be used to refer to me.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1546
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1547 In Lisp, one set of instructions can be attached to several names.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1548 For example, the computer instructions for adding numbers can be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1549 linked to the symbol @code{plus} as well as to the symbol @code{+}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1550 (and are in some dialects of Lisp). Among humans, I can be referred
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1551 to as @samp{Robert} as well as @samp{Bob} and by other words as well.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1552
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1553 On the other hand, a symbol can have only one function definition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1554 attached to it at a time. Otherwise, the computer would be confused as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1555 to which definition to use. If this were the case among people, only
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1556 one person in the world could be named @samp{Bob}. However, the function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1557 definition to which the name refers can be changed readily.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1558 (@xref{Install, , Install a Function Definition}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1559
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1560 Since Emacs Lisp is large, it is customary to name symbols in a way
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1561 that identifies the part of Emacs to which the function belongs.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1562 Thus, all the names for functions that deal with Texinfo start with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1563 @samp{texinfo-} and those for functions that deal with reading mail
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1564 start with @samp{rmail-}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1565
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1566 @node Lisp Interpreter, Evaluation, Names & Definitions, List Processing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1567 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1568 @section The Lisp Interpreter
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1569 @cindex Lisp interpreter, what it does
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1570 @cindex Interpreter, what it does
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1571
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1572 Based on what we have seen, we can now start to figure out what the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1573 Lisp interpreter does when we command it to evaluate a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1574 First, it looks to see whether there is a quote before the list; if
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1575 there is, the interpreter just gives us the list. On the other
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1576 hand, if there is no quote, the interpreter looks at the first element
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1577 in the list and sees whether it has a function definition. If it does,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1578 the interpreter carries out the instructions in the function definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1579 Otherwise, the interpreter prints an error message.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1580
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1581 This is how Lisp works. Simple. There are added complications which we
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1582 will get to in a minute, but these are the fundamentals. Of course, to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1583 write Lisp programs, you need to know how to write function definitions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1584 and attach them to names, and how to do this without confusing either
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1585 yourself or the computer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1586
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1587 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1588 * Complications:: Variables, Special forms, Lists within.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1589 * Byte Compiling:: Specially processing code for speed.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1590 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1591
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1592 @node Complications, Byte Compiling, Lisp Interpreter, Lisp Interpreter
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1593 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1594 @unnumberedsubsec Complications
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1595 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1596
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1597 Now, for the first complication. In addition to lists, the Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1598 interpreter can evaluate a symbol that is not quoted and does not have
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1599 parentheses around it. The Lisp interpreter will attempt to determine
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1600 the symbol's value as a @dfn{variable}. This situation is described
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1601 in the section on variables. (@xref{Variables}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1602
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1603 @cindex Special form
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1604 The second complication occurs because some functions are unusual and do
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1605 not work in the usual manner. Those that don't are called @dfn{special
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1606 forms}. They are used for special jobs, like defining a function, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1607 there are not many of them. In the next few chapters, you will be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1608 introduced to several of the more important special forms.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1609
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1610 The third and final complication is this: if the function that the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1611 Lisp interpreter is looking at is not a special form, and if it is part
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1612 of a list, the Lisp interpreter looks to see whether the list has a list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1613 inside of it. If there is an inner list, the Lisp interpreter first
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1614 figures out what it should do with the inside list, and then it works on
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1615 the outside list. If there is yet another list embedded inside the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1616 inner list, it works on that one first, and so on. It always works on
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1617 the innermost list first. The interpreter works on the innermost list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1618 first, to evaluate the result of that list. The result may be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1619 used by the enclosing expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1620
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1621 Otherwise, the interpreter works left to right, from one expression to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1622 the next.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1623
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1624 @node Byte Compiling, , Complications, Lisp Interpreter
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1625 @subsection Byte Compiling
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1626 @cindex Byte compiling
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1627
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1628 One other aspect of interpreting: the Lisp interpreter is able to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1629 interpret two kinds of entity: humanly readable code, on which we will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1630 focus exclusively, and specially processed code, called @dfn{byte
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1631 compiled} code, which is not humanly readable. Byte compiled code
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1632 runs faster than humanly readable code.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1633
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1634 You can transform humanly readable code into byte compiled code by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1635 running one of the compile commands such as @code{byte-compile-file}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1636 Byte compiled code is usually stored in a file that ends with a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1637 @file{.elc} extension rather than a @file{.el} extension. You will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1638 see both kinds of file in the @file{emacs/lisp} directory; the files
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1639 to read are those with @file{.el} extensions.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1640
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1641 As a practical matter, for most things you might do to customize or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1642 extend Emacs, you do not need to byte compile; and I will not discuss
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1643 the topic here. @xref{Byte Compilation, , Byte Compilation, elisp,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1644 The GNU Emacs Lisp Reference Manual}, for a full description of byte
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1645 compilation.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1646
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1647 @node Evaluation, Variables, Lisp Interpreter, List Processing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1648 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1649 @section Evaluation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1650 @cindex Evaluation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1651
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1652 When the Lisp interpreter works on an expression, the term for the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1653 activity is called @dfn{evaluation}. We say that the interpreter
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1654 `evaluates the expression'. I've used this term several times before.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1655 The word comes from its use in everyday language, `to ascertain the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1656 value or amount of; to appraise', according to @cite{Webster's New
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1657 Collegiate Dictionary}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1658
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1659 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1660 * How the Interpreter Acts:: Returns and Side Effects...
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1661 * Evaluating Inner Lists:: Lists within lists...
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1662 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1663
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1664 @node How the Interpreter Acts, Evaluating Inner Lists, Evaluation, Evaluation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1665 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1666 @unnumberedsubsec How the Lisp Interpreter Acts
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1667 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1668
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1669 @cindex @samp{returned value} explained
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1670 After evaluating an expression, the Lisp interpreter will most likely
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1671 @dfn{return} the value that the computer produces by carrying out the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1672 instructions it found in the function definition, or perhaps it will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1673 give up on that function and produce an error message. (The interpreter
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1674 may also find itself tossed, so to speak, to a different function or it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1675 may attempt to repeat continually what it is doing for ever and ever in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1676 what is called an `infinite loop'. These actions are less common; and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1677 we can ignore them.) Most frequently, the interpreter returns a value.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1678
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1679 @cindex @samp{side effect} defined
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1680 At the same time the interpreter returns a value, it may do something
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1681 else as well, such as move a cursor or copy a file; this other kind of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1682 action is called a @dfn{side effect}. Actions that we humans think are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1683 important, such as printing results, are often ``side effects'' to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1684 Lisp interpreter. The jargon can sound peculiar, but it turns out that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1685 it is fairly easy to learn to use side effects.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1686
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1687 In summary, evaluating a symbolic expression most commonly causes the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1688 Lisp interpreter to return a value and perhaps carry out a side effect;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1689 or else produce an error.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1690
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1691 @node Evaluating Inner Lists, , How the Interpreter Acts, Evaluation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1692 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1693 @subsection Evaluating Inner Lists
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1694 @cindex Inner list evaluation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1695 @cindex Evaluating inner lists
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1696
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1697 If evaluation applies to a list that is inside another list, the outer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1698 list may use the value returned by the first evaluation as information
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1699 when the outer list is evaluated. This explains why inner expressions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1700 are evaluated first: the values they return are used by the outer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1701 expressions.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1702
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1703 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1704 We can investigate this process by evaluating another addition example.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1705 Place your cursor after the following expression and type @kbd{C-x C-e}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1706
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1707 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1708 (+ 2 (+ 3 3))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1709 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1710
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1711 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1712 The number 8 will appear in the echo area.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1713
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1714 What happens is that the Lisp interpreter first evaluates the inner
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1715 expression, @code{(+ 3 3)}, for which the value 6 is returned; then it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1716 evaluates the outer expression as if it were written @code{(+ 2 6)}, which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1717 returns the value 8. Since there are no more enclosing expressions to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1718 evaluate, the interpreter prints that value in the echo area.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1719
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1720 Now it is easy to understand the name of the command invoked by the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1721 keystrokes @kbd{C-x C-e}: the name is @code{eval-last-sexp}. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1722 letters @code{sexp} are an abbreviation for `symbolic expression', and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1723 @code{eval} is an abbreviation for `evaluate'. The command means
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1724 `evaluate last symbolic expression'.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1725
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1726 As an experiment, you can try evaluating the expression by putting the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1727 cursor at the beginning of the next line immediately following the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1728 expression, or inside the expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1729
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1730 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1731 Here is another copy of the expression:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1732
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1733 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1734 (+ 2 (+ 3 3))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1735 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1736
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1737 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1738 If you place the cursor at the beginning of the blank line that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1739 immediately follows the expression and type @kbd{C-x C-e}, you will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1740 still get the value 8 printed in the echo area. Now try putting the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1741 cursor inside the expression. If you put it right after the next to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1742 last parenthesis (so it appears to sit on top of the last parenthesis),
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1743 you will get a 6 printed in the echo area! This is because the command
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1744 evaluates the expression @code{(+ 3 3)}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1745
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1746 Now put the cursor immediately after a number. Type @kbd{C-x C-e} and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1747 you will get the number itself. In Lisp, if you evaluate a number, you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1748 get the number itself---this is how numbers differ from symbols. If you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1749 evaluate a list starting with a symbol like @code{+}, you will get a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1750 value returned that is the result of the computer carrying out the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1751 instructions in the function definition attached to that name. If a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1752 symbol by itself is evaluated, something different happens, as we will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1753 see in the next section.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1754
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1755 @node Variables, Arguments, Evaluation, List Processing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1756 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1757 @section Variables
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1758 @cindex Variables
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1759
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1760 In Emacs Lisp, a symbol can have a value attached to it just as it can
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1761 have a function definition attached to it. The two are different.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1762 The function definition is a set of instructions that a computer will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1763 obey. A value, on the other hand, is something, such as number or a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1764 name, that can vary (which is why such a symbol is called a variable).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1765 The value of a symbol can be any expression in Lisp, such as a symbol,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1766 number, list, or string. A symbol that has a value is often called a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1767 @dfn{variable}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1768
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1769 A symbol can have both a function definition and a value attached to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1770 it at the same time. Or it can have just one or the other.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1771 The two are separate. This is somewhat similar
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1772 to the way the name Cambridge can refer to the city in Massachusetts
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1773 and have some information attached to the name as well, such as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1774 ``great programming center''.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1775
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1776 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1777 (Incidentally, in Emacs Lisp, a symbol can have two
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1778 other things attached to it, too: a property list and a documentation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1779 string; these are discussed later.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1780 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1781
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1782 Another way to think about this is to imagine a symbol as being a chest
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1783 of drawers. The function definition is put in one drawer, the value in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1784 another, and so on. What is put in the drawer holding the value can be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1785 changed without affecting the contents of the drawer holding the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1786 function definition, and vice-verse.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1787
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1788 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1789 * fill-column Example::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1790 * Void Function:: The error message for a symbol
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1791 without a function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1792 * Void Variable:: The error message for a symbol without a value.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1793 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1794
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1795 @node fill-column Example, Void Function, Variables, Variables
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1796 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1797 @unnumberedsubsec @code{fill-column}, an Example Variable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1798 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1799
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1800 @findex fill-column, @r{an example variable}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1801 @cindex Example variable, @code{fill-column}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1802 @cindex Variable, example of, @code{fill-column}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1803 The variable @code{fill-column} illustrates a symbol with a value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1804 attached to it: in every GNU Emacs buffer, this symbol is set to some
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1805 value, usually 72 or 70, but sometimes to some other value. To find the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1806 value of this symbol, evaluate it by itself. If you are reading this in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1807 Info inside of GNU Emacs, you can do this by putting the cursor after
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1808 the symbol and typing @kbd{C-x C-e}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1809
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1810 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1811 fill-column
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1812 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1813
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1814 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1815 After I typed @kbd{C-x C-e}, Emacs printed the number 72 in my echo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1816 area. This is the value for which @code{fill-column} is set for me as I
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1817 write this. It may be different for you in your Info buffer. Notice
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1818 that the value returned as a variable is printed in exactly the same way
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1819 as the value returned by a function carrying out its instructions. From
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1820 the point of view of the Lisp interpreter, a value returned is a value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1821 returned. What kind of expression it came from ceases to matter once
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1822 the value is known.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1823
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1824 A symbol can have any value attached to it or, to use the jargon, we can
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1825 @dfn{bind} the variable to a value: to a number, such as 72; to a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1826 string, @code{"such as this"}; to a list, such as @code{(spruce pine
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1827 oak)}; we can even bind a variable to a function definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1828
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1829 A symbol can be bound to a value in several ways. @xref{set & setq, ,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1830 Setting the Value of a Variable}, for information about one way to do
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1831 this.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1832
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1833 @node Void Function, Void Variable, fill-column Example, Variables
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1834 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1835 @subsection Error Message for a Symbol Without a Function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1836 @cindex Symbol without function error
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1837 @cindex Error for symbol without function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1838
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1839 When we evaluated @code{fill-column} to find its value as a variable,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1840 we did not place parentheses around the word. This is because we did
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1841 not intend to use it as a function name.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1842
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1843 If @code{fill-column} were the first or only element of a list, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1844 Lisp interpreter would attempt to find the function definition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1845 attached to it. But @code{fill-column} has no function definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1846 Try evaluating this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1847
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1848 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1849 (fill-column)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1850 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1851
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1852 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1853 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1854 In GNU Emacs version 22, you will create a @file{*Backtrace*} buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1855 that says:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1856
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1857 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1858 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1859 ---------- Buffer: *Backtrace* ----------
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1860 Debugger entered--Lisp error: (void-function fill-column)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1861 (fill-column)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1862 eval((fill-column))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1863 eval-last-sexp-1(nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1864 eval-last-sexp(nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1865 call-interactively(eval-last-sexp)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1866 ---------- Buffer: *Backtrace* ----------
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1867 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1868 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1869
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1870 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1871 (Remember, to quit the debugger and make the debugger window go away,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1872 type @kbd{q} in the @file{*Backtrace*} buffer.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1873
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1874 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1875 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1876 In GNU Emacs 20 and before, you will produce an error message that says:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1877
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1878 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1879 Symbol's function definition is void:@: fill-column
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1880 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1881
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1882 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1883 (The message will go away as soon as you move the cursor or type
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1884 another key.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1885 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1886
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1887 @node Void Variable, , Void Function, Variables
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1888 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1889 @subsection Error Message for a Symbol Without a Value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1890 @cindex Symbol without value error
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1891 @cindex Error for symbol without value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1892
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1893 If you attempt to evaluate a symbol that does not have a value bound to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1894 it, you will receive an error message. You can see this by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1895 experimenting with our 2 plus 2 addition. In the following expression,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1896 put your cursor right after the @code{+}, before the first number 2,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1897 type @kbd{C-x C-e}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1898
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1899 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1900 (+ 2 2)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1901 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1902
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1903 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1904 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1905 In GNU Emacs 22, you will create a @file{*Backtrace*} buffer that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1906 says:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1907
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1908 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1909 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1910 ---------- Buffer: *Backtrace* ----------
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1911 Debugger entered--Lisp error: (void-variable +)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1912 eval(+)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1913 eval-last-sexp-1(nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1914 eval-last-sexp(nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1915 call-interactively(eval-last-sexp)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1916 ---------- Buffer: *Backtrace* ----------
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1917 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1918 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1919
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1920 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1921 (As with the other times we entered the debugger, you can quit by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1922 typing @kbd{q} in the @file{*Backtrace*} buffer.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1923
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1924 This backtrace is different from the very first error message we saw,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1925 which said, @samp{Debugger entered--Lisp error: (void-function this)}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1926 In this case, the function does not have a value as a variable; while
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1927 in the other error message, the function (the word `this') did not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1928 have a definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1929
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1930 In this experiment with the @code{+}, what we did was cause the Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1931 interpreter to evaluate the @code{+} and look for the value of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1932 variable instead of the function definition. We did this by placing the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1933 cursor right after the symbol rather than after the parenthesis of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1934 enclosing list as we did before. As a consequence, the Lisp interpreter
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1935 evaluated the preceding s-expression, which in this case was the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1936 @code{+} by itself.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1937
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1938 Since @code{+} does not have a value bound to it, just the function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1939 definition, the error message reported that the symbol's value as a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1940 variable was void.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1941
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1942 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1943 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1944 In GNU Emacs version 20 and before, your error message will say:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1945
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1946 @example
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1947 Symbol's value as variable is void:@: +
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1948 @end example
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1949
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1950 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1951 The meaning is the same as in GNU Emacs 22.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1952 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1953
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1954 @node Arguments, set & setq, Variables, List Processing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1955 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1956 @section Arguments
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1957 @cindex Arguments
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1958 @cindex Passing information to functions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1959
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1960 To see how information is passed to functions, let's look again at
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1961 our old standby, the addition of two plus two. In Lisp, this is written
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1962 as follows:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1963
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1964 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1965 (+ 2 2)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1966 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1967
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1968 If you evaluate this expression, the number 4 will appear in your echo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1969 area. What the Lisp interpreter does is add the numbers that follow
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1970 the @code{+}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1971
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1972 @cindex @samp{argument} defined
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1973 The numbers added by @code{+} are called the @dfn{arguments} of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1974 function @code{+}. These numbers are the information that is given to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1975 or @dfn{passed} to the function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1976
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1977 The word `argument' comes from the way it is used in mathematics and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1978 does not refer to a disputation between two people; instead it refers to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1979 the information presented to the function, in this case, to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1980 @code{+}. In Lisp, the arguments to a function are the atoms or lists
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1981 that follow the function. The values returned by the evaluation of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1982 these atoms or lists are passed to the function. Different functions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1983 require different numbers of arguments; some functions require none at
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1984 all.@footnote{It is curious to track the path by which the word `argument'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1985 came to have two different meanings, one in mathematics and the other in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1986 everyday English. According to the @cite{Oxford English Dictionary},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1987 the word derives from the Latin for @samp{to make clear, prove}; thus it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1988 came to mean, by one thread of derivation, `the evidence offered as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1989 proof', which is to say, `the information offered', which led to its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1990 meaning in Lisp. But in the other thread of derivation, it came to mean
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1991 `to assert in a manner against which others may make counter
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1992 assertions', which led to the meaning of the word as a disputation.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1993 (Note here that the English word has two different definitions attached
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1994 to it at the same time. By contrast, in Emacs Lisp, a symbol cannot
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1995 have two different function definitions at the same time.)}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1996
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1997 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1998 * Data types:: Types of data passed to a function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1999 * Args as Variable or List:: An argument can be the value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2000 of a variable or list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2001 * Variable Number of Arguments:: Some functions may take a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2002 variable number of arguments.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2003 * Wrong Type of Argument:: Passing an argument of the wrong type
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2004 to a function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2005 * message:: A useful function for sending messages.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2006 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2007
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2008 @node Data types, Args as Variable or List, Arguments, Arguments
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2009 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2010 @subsection Arguments' Data Types
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2011 @cindex Data types
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2012 @cindex Types of data
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2013 @cindex Arguments' data types
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2014
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2015 The type of data that should be passed to a function depends on what
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2016 kind of information it uses. The arguments to a function such as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2017 @code{+} must have values that are numbers, since @code{+} adds numbers.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2018 Other functions use different kinds of data for their arguments.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2019
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2020 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2021 @findex concat
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2022 For example, the @code{concat} function links together or unites two or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2023 more strings of text to produce a string. The arguments are strings.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2024 Concatenating the two character strings @code{abc}, @code{def} produces
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2025 the single string @code{abcdef}. This can be seen by evaluating the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2026 following:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2027
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2028 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2029 (concat "abc" "def")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2030 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2031
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2032 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2033 The value produced by evaluating this expression is @code{"abcdef"}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2034
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2035 A function such as @code{substring} uses both a string and numbers as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2036 arguments. The function returns a part of the string, a substring of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2037 the first argument. This function takes three arguments. Its first
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2038 argument is the string of characters, the second and third arguments are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2039 numbers that indicate the beginning and end of the substring. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2040 numbers are a count of the number of characters (including spaces and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2041 punctuations) from the beginning of the string.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2042
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2043 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2044 For example, if you evaluate the following:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2045
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2046 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2047 (substring "The quick brown fox jumped." 16 19)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2048 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2049
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2050 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2051 you will see @code{"fox"} appear in the echo area. The arguments are the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2052 string and the two numbers.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2053
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2054 Note that the string passed to @code{substring} is a single atom even
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2055 though it is made up of several words separated by spaces. Lisp counts
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2056 everything between the two quotation marks as part of the string,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2057 including the spaces. You can think of the @code{substring} function as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2058 a kind of `atom smasher' since it takes an otherwise indivisible atom
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2059 and extracts a part. However, @code{substring} is only able to extract
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2060 a substring from an argument that is a string, not from another type of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2061 atom such as a number or symbol.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2062
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2063 @node Args as Variable or List, Variable Number of Arguments, Data types, Arguments
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2064 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2065 @subsection An Argument as the Value of a Variable or List
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2066
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2067 An argument can be a symbol that returns a value when it is evaluated.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2068 For example, when the symbol @code{fill-column} by itself is evaluated,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2069 it returns a number. This number can be used in an addition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2070
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2071 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2072 Position the cursor after the following expression and type @kbd{C-x
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2073 C-e}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2074
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2075 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2076 (+ 2 fill-column)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2077 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2078
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2079 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2080 The value will be a number two more than what you get by evaluating
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2081 @code{fill-column} alone. For me, this is 74, because my value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2082 @code{fill-column} is 72.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2083
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2084 As we have just seen, an argument can be a symbol that returns a value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2085 when evaluated. In addition, an argument can be a list that returns a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2086 value when it is evaluated. For example, in the following expression,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2087 the arguments to the function @code{concat} are the strings
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2088 @w{@code{"The "}} and @w{@code{" red foxes."}} and the list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2089 @code{(number-to-string (+ 2 fill-column))}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2090
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2091 @c For GNU Emacs 22, need number-to-string
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2092 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2093 (concat "The " (number-to-string (+ 2 fill-column)) " red foxes.")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2094 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2095
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2096 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2097 If you evaluate this expression---and if, as with my Emacs,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2098 @code{fill-column} evaluates to 72---@code{"The 74 red foxes."} will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2099 appear in the echo area. (Note that you must put spaces after the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2100 word @samp{The} and before the word @samp{red} so they will appear in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2101 the final string. The function @code{number-to-string} converts the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2102 integer that the addition function returns to a string.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2103 @code{number-to-string} is also known as @code{int-to-string}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2104
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2105 @node Variable Number of Arguments, Wrong Type of Argument, Args as Variable or List, Arguments
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2106 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2107 @subsection Variable Number of Arguments
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2108 @cindex Variable number of arguments
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2109 @cindex Arguments, variable number of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2110
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2111 Some functions, such as @code{concat}, @code{+} or @code{*}, take any
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2112 number of arguments. (The @code{*} is the symbol for multiplication.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2113 This can be seen by evaluating each of the following expressions in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2114 the usual way. What you will see in the echo area is printed in this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2115 text after @samp{@result{}}, which you may read as `evaluates to'.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2116
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2117 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2118 In the first set, the functions have no arguments:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2119
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2120 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2121 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2122 (+) @result{} 0
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2123
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2124 (*) @result{} 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2125 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2126 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2127
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2128 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2129 In this set, the functions have one argument each:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2130
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2131 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2132 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2133 (+ 3) @result{} 3
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2134
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2135 (* 3) @result{} 3
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2136 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2137 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2138
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2139 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2140 In this set, the functions have three arguments each:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2141
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2142 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2143 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2144 (+ 3 4 5) @result{} 12
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2145
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2146 (* 3 4 5) @result{} 60
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2147 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2148 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2149
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2150 @node Wrong Type of Argument, message, Variable Number of Arguments, Arguments
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2151 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2152 @subsection Using the Wrong Type Object as an Argument
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2153 @cindex Wrong type of argument
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2154 @cindex Argument, wrong type of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2155
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2156 When a function is passed an argument of the wrong type, the Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2157 interpreter produces an error message. For example, the @code{+}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2158 function expects the values of its arguments to be numbers. As an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2159 experiment we can pass it the quoted symbol @code{hello} instead of a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2160 number. Position the cursor after the following expression and type
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2161 @kbd{C-x C-e}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2162
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2163 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2164 (+ 2 'hello)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2165 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2166
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2167 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2168 When you do this you will generate an error message. What has happened
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2169 is that @code{+} has tried to add the 2 to the value returned by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2170 @code{'hello}, but the value returned by @code{'hello} is the symbol
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2171 @code{hello}, not a number. Only numbers can be added. So @code{+}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2172 could not carry out its addition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2173
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2174 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2175 In GNU Emacs version 22, you will create and enter a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2176 @file{*Backtrace*} buffer that says:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2177
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2178 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2179 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2180 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2181 ---------- Buffer: *Backtrace* ----------
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2182 Debugger entered--Lisp error:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2183 (wrong-type-argument number-or-marker-p hello)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2184 +(2 hello)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2185 eval((+ 2 (quote hello)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2186 eval-last-sexp-1(nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2187 eval-last-sexp(nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2188 call-interactively(eval-last-sexp)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2189 ---------- Buffer: *Backtrace* ----------
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2190 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2191 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2192
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2193 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2194 As usual, the error message tries to be helpful and makes sense after you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2195 learn how to read it.@footnote{@code{(quote hello)} is an expansion of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2196 the abbreviation @code{'hello}.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2197
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2198 The first part of the error message is straightforward; it says
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2199 @samp{wrong type argument}. Next comes the mysterious jargon word
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2200 @w{@samp{number-or-marker-p}}. This word is trying to tell you what
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2201 kind of argument the @code{+} expected.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2202
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2203 The symbol @code{number-or-marker-p} says that the Lisp interpreter is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2204 trying to determine whether the information presented it (the value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2205 the argument) is a number or a marker (a special object representing a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2206 buffer position). What it does is test to see whether the @code{+} is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2207 being given numbers to add. It also tests to see whether the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2208 argument is something called a marker, which is a specific feature of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2209 Emacs Lisp. (In Emacs, locations in a buffer are recorded as markers.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2210 When the mark is set with the @kbd{C-@@} or @kbd{C-@key{SPC}} command,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2211 its position is kept as a marker. The mark can be considered a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2212 number---the number of characters the location is from the beginning
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2213 of the buffer.) In Emacs Lisp, @code{+} can be used to add the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2214 numeric value of marker positions as numbers.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2215
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2216 The @samp{p} of @code{number-or-marker-p} is the embodiment of a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2217 practice started in the early days of Lisp programming. The @samp{p}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2218 stands for `predicate'. In the jargon used by the early Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2219 researchers, a predicate refers to a function to determine whether some
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2220 property is true or false. So the @samp{p} tells us that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2221 @code{number-or-marker-p} is the name of a function that determines
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2222 whether it is true or false that the argument supplied is a number or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2223 a marker. Other Lisp symbols that end in @samp{p} include @code{zerop},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2224 a function that tests whether its argument has the value of zero, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2225 @code{listp}, a function that tests whether its argument is a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2226
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2227 Finally, the last part of the error message is the symbol @code{hello}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2228 This is the value of the argument that was passed to @code{+}. If the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2229 addition had been passed the correct type of object, the value passed
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2230 would have been a number, such as 37, rather than a symbol like
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2231 @code{hello}. But then you would not have got the error message.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2232
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2233 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2234 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2235 In GNU Emacs version 20 and before, the echo area displays an error
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2236 message that says:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2237
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2238 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2239 Wrong type argument:@: number-or-marker-p, hello
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2240 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2241
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2242 This says, in different words, the same as the top line of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2243 @file{*Backtrace*} buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2244 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2245
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2246 @node message, , Wrong Type of Argument, Arguments
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2247 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2248 @subsection The @code{message} Function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2249 @findex message
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2251 Like @code{+}, the @code{message} function takes a variable number of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2252 arguments. It is used to send messages to the user and is so useful
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2253 that we will describe it here.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2254
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2255 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2256 A message is printed in the echo area. For example, you can print a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2257 message in your echo area by evaluating the following list:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2258
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2259 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2260 (message "This message appears in the echo area!")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2261 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2262
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2263 The whole string between double quotation marks is a single argument
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2264 and is printed @i{in toto}. (Note that in this example, the message
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2265 itself will appear in the echo area within double quotes; that is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2266 because you see the value returned by the @code{message} function. In
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2267 most uses of @code{message} in programs that you write, the text will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2268 be printed in the echo area as a side-effect, without the quotes.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2269 @xref{multiply-by-seven in detail, , @code{multiply-by-seven} in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2270 detail}, for an example of this.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2271
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2272 However, if there is a @samp{%s} in the quoted string of characters, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2273 @code{message} function does not print the @samp{%s} as such, but looks
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2274 to the argument that follows the string. It evaluates the second
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2275 argument and prints the value at the location in the string where the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2276 @samp{%s} is.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2277
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2278 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2279 You can see this by positioning the cursor after the following
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2280 expression and typing @kbd{C-x C-e}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2281
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2282 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2283 (message "The name of this buffer is: %s." (buffer-name))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2284 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2285
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2286 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2287 In Info, @code{"The name of this buffer is: *info*."} will appear in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2288 echo area. The function @code{buffer-name} returns the name of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2289 buffer as a string, which the @code{message} function inserts in place
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2290 of @code{%s}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2291
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2292 To print a value as an integer, use @samp{%d} in the same way as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2293 @samp{%s}. For example, to print a message in the echo area that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2294 states the value of the @code{fill-column}, evaluate the following:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2295
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2296 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2297 (message "The value of fill-column is %d." fill-column)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2298 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2299
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2300 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2301 On my system, when I evaluate this list, @code{"The value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2302 fill-column is 72."} appears in my echo area@footnote{Actually, you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2303 can use @code{%s} to print a number. It is non-specific. @code{%d}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2304 prints only the part of a number left of a decimal point, and not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2305 anything that is not a number.}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2306
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2307 If there is more than one @samp{%s} in the quoted string, the value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2308 the first argument following the quoted string is printed at the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2309 location of the first @samp{%s} and the value of the second argument is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2310 printed at the location of the second @samp{%s}, and so on.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2311
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2312 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2313 For example, if you evaluate the following,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2314
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2315 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2316 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2317 (message "There are %d %s in the office!"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2318 (- fill-column 14) "pink elephants")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2319 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2320 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2321
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2322 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2323 a rather whimsical message will appear in your echo area. On my system
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2324 it says, @code{"There are 58 pink elephants in the office!"}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2325
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2326 The expression @code{(- fill-column 14)} is evaluated and the resulting
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2327 number is inserted in place of the @samp{%d}; and the string in double
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2328 quotes, @code{"pink elephants"}, is treated as a single argument and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2329 inserted in place of the @samp{%s}. (That is to say, a string between
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2330 double quotes evaluates to itself, like a number.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2331
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2332 Finally, here is a somewhat complex example that not only illustrates
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2333 the computation of a number, but also shows how you can use an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2334 expression within an expression to generate the text that is substituted
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2335 for @samp{%s}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2336
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2337 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2338 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2339 (message "He saw %d %s"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2340 (- fill-column 32)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2341 (concat "red "
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2342 (substring
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2343 "The quick brown foxes jumped." 16 21)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2344 " leaping."))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2345 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2346 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2347
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2348 In this example, @code{message} has three arguments: the string,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2349 @code{"He saw %d %s"}, the expression, @code{(- fill-column 32)}, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2350 the expression beginning with the function @code{concat}. The value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2351 resulting from the evaluation of @code{(- fill-column 32)} is inserted
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2352 in place of the @samp{%d}; and the value returned by the expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2353 beginning with @code{concat} is inserted in place of the @samp{%s}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2354
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2355 When your fill column is 70 and you evaluate the expression, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2356 message @code{"He saw 38 red foxes leaping."} appears in your echo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2357 area.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2358
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2359 @node set & setq, Summary, Arguments, List Processing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2360 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2361 @section Setting the Value of a Variable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2362 @cindex Variable, setting value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2363 @cindex Setting value of variable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2364
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2365 @cindex @samp{bind} defined
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2366 There are several ways by which a variable can be given a value. One of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2367 the ways is to use either the function @code{set} or the function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2368 @code{setq}. Another way is to use @code{let} (@pxref{let}). (The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2369 jargon for this process is to @dfn{bind} a variable to a value.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2370
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2371 The following sections not only describe how @code{set} and @code{setq}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2372 work but also illustrate how arguments are passed.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2373
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2374 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2375 * Using set:: Setting values.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2376 * Using setq:: Setting a quoted value.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2377 * Counting:: Using @code{setq} to count.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2378 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2379
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2380 @node Using set, Using setq, set & setq, set & setq
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2381 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2382 @subsection Using @code{set}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2383 @findex set
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2384
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2385 To set the value of the symbol @code{flowers} to the list @code{'(rose
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2386 violet daisy buttercup)}, evaluate the following expression by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2387 positioning the cursor after the expression and typing @kbd{C-x C-e}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2388
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2389 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2390 (set 'flowers '(rose violet daisy buttercup))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2391 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2392
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2393 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2394 The list @code{(rose violet daisy buttercup)} will appear in the echo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2395 area. This is what is @emph{returned} by the @code{set} function. As a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2396 side effect, the symbol @code{flowers} is bound to the list; that is,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2397 the symbol @code{flowers}, which can be viewed as a variable, is given
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2398 the list as its value. (This process, by the way, illustrates how a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2399 side effect to the Lisp interpreter, setting the value, can be the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2400 primary effect that we humans are interested in. This is because every
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2401 Lisp function must return a value if it does not get an error, but it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2402 will only have a side effect if it is designed to have one.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2403
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2404 After evaluating the @code{set} expression, you can evaluate the symbol
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2405 @code{flowers} and it will return the value you just set. Here is the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2406 symbol. Place your cursor after it and type @kbd{C-x C-e}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2407
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2408 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2409 flowers
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2410 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2411
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2412 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2413 When you evaluate @code{flowers}, the list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2414 @code{(rose violet daisy buttercup)} appears in the echo area.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2415
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2416 Incidentally, if you evaluate @code{'flowers}, the variable with a quote
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2417 in front of it, what you will see in the echo area is the symbol itself,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2418 @code{flowers}. Here is the quoted symbol, so you can try this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2419
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2420 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2421 'flowers
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2422 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2423
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2424 Note also, that when you use @code{set}, you need to quote both
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2425 arguments to @code{set}, unless you want them evaluated. Since we do
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2426 not want either argument evaluated, neither the variable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2427 @code{flowers} nor the list @code{(rose violet daisy buttercup)}, both
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2428 are quoted. (When you use @code{set} without quoting its first
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2429 argument, the first argument is evaluated before anything else is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2430 done. If you did this and @code{flowers} did not have a value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2431 already, you would get an error message that the @samp{Symbol's value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2432 as variable is void}; on the other hand, if @code{flowers} did return
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2433 a value after it was evaluated, the @code{set} would attempt to set
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2434 the value that was returned. There are situations where this is the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2435 right thing for the function to do; but such situations are rare.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2436
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2437 @node Using setq, Counting, Using set, set & setq
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2438 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2439 @subsection Using @code{setq}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2440 @findex setq
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2441
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2442 As a practical matter, you almost always quote the first argument to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2443 @code{set}. The combination of @code{set} and a quoted first argument
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2444 is so common that it has its own name: the special form @code{setq}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2445 This special form is just like @code{set} except that the first argument
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2446 is quoted automatically, so you don't need to type the quote mark
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2447 yourself. Also, as an added convenience, @code{setq} permits you to set
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2448 several different variables to different values, all in one expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2449
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2450 To set the value of the variable @code{carnivores} to the list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2451 @code{'(lion tiger leopard)} using @code{setq}, the following expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2452 is used:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2453
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2454 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2455 (setq carnivores '(lion tiger leopard))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2456 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2457
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2458 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2459 This is exactly the same as using @code{set} except the first argument
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2460 is automatically quoted by @code{setq}. (The @samp{q} in @code{setq}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2461 means @code{quote}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2462
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2463 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2464 With @code{set}, the expression would look like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2465
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2466 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2467 (set 'carnivores '(lion tiger leopard))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2468 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2469
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2470 Also, @code{setq} can be used to assign different values to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2471 different variables. The first argument is bound to the value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2472 of the second argument, the third argument is bound to the value of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2473 fourth argument, and so on. For example, you could use the following to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2474 assign a list of trees to the symbol @code{trees} and a list of herbivores
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2475 to the symbol @code{herbivores}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2476
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2477 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2478 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2479 (setq trees '(pine fir oak maple)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2480 herbivores '(gazelle antelope zebra))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2481 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2482 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2483
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2484 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2485 (The expression could just as well have been on one line, but it might
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2486 not have fit on a page; and humans find it easier to read nicely
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2487 formatted lists.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2488
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2489 Although I have been using the term `assign', there is another way of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2490 thinking about the workings of @code{set} and @code{setq}; and that is to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2491 say that @code{set} and @code{setq} make the symbol @emph{point} to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2492 list. This latter way of thinking is very common and in forthcoming
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2493 chapters we shall come upon at least one symbol that has `pointer' as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2494 part of its name. The name is chosen because the symbol has a value,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2495 specifically a list, attached to it; or, expressed another way,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2496 the symbol is set to ``point'' to the list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2497
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2498 @node Counting, , Using setq, set & setq
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2499 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2500 @subsection Counting
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2501 @cindex Counting
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2502
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2503 Here is an example that shows how to use @code{setq} in a counter. You
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2504 might use this to count how many times a part of your program repeats
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2505 itself. First set a variable to zero; then add one to the number each
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2506 time the program repeats itself. To do this, you need a variable that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2507 serves as a counter, and two expressions: an initial @code{setq}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2508 expression that sets the counter variable to zero; and a second
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2509 @code{setq} expression that increments the counter each time it is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2510 evaluated.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2511
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2512 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2513 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2514 (setq counter 0) ; @r{Let's call this the initializer.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2515
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2516 (setq counter (+ counter 1)) ; @r{This is the incrementer.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2517
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2518 counter ; @r{This is the counter.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2519 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2520 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2521
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2522 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2523 (The text following the @samp{;} are comments. @xref{Change a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2524 defun, , Change a Function Definition}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2525
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2526 If you evaluate the first of these expressions, the initializer,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2527 @code{(setq counter 0)}, and then evaluate the third expression,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2528 @code{counter}, the number @code{0} will appear in the echo area. If
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2529 you then evaluate the second expression, the incrementer, @code{(setq
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2530 counter (+ counter 1))}, the counter will get the value 1. So if you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2531 again evaluate @code{counter}, the number @code{1} will appear in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2532 echo area. Each time you evaluate the second expression, the value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2533 the counter will be incremented.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2534
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2535 When you evaluate the incrementer, @code{(setq counter (+ counter 1))},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2536 the Lisp interpreter first evaluates the innermost list; this is the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2537 addition. In order to evaluate this list, it must evaluate the variable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2538 @code{counter} and the number @code{1}. When it evaluates the variable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2539 @code{counter}, it receives its current value. It passes this value and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2540 the number @code{1} to the @code{+} which adds them together. The sum
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2541 is then returned as the value of the inner list and passed to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2542 @code{setq} which sets the variable @code{counter} to this new value.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2543 Thus, the value of the variable, @code{counter}, is changed.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2544
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2545 @node Summary, Error Message Exercises, set & setq, List Processing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2546 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2547 @section Summary
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2548
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2549 Learning Lisp is like climbing a hill in which the first part is the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2550 steepest. You have now climbed the most difficult part; what remains
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2551 becomes easier as you progress onwards.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2552
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2553 @need 1000
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2554 In summary,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2555
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2556 @itemize @bullet
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2557
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2558 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2559 Lisp programs are made up of expressions, which are lists or single atoms.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2560
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2561 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2562 Lists are made up of zero or more atoms or inner lists, separated by whitespace and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2563 surrounded by parentheses. A list can be empty.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2564
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2565 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2566 Atoms are multi-character symbols, like @code{forward-paragraph}, single
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2567 character symbols like @code{+}, strings of characters between double
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2568 quotation marks, or numbers.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2569
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2570 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2571 A number evaluates to itself.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2572
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2573 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2574 A string between double quotes also evaluates to itself.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2575
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2576 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2577 When you evaluate a symbol by itself, its value is returned.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2578
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2579 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2580 When you evaluate a list, the Lisp interpreter looks at the first symbol
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2581 in the list and then at the function definition bound to that symbol.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2582 Then the instructions in the function definition are carried out.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2583
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2584 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2585 A single quotation mark,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2586 @ifinfo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2587 '
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2588 @end ifinfo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2589 @ifnotinfo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2590 @code{'}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2591 @end ifnotinfo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2592 , tells the Lisp interpreter that it should
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2593 return the following expression as written, and not evaluate it as it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2594 would if the quote were not there.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2595
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2596 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2597 Arguments are the information passed to a function. The arguments to a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2598 function are computed by evaluating the rest of the elements of the list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2599 of which the function is the first element.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2600
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2601 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2602 A function always returns a value when it is evaluated (unless it gets
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2603 an error); in addition, it may also carry out some action called a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2604 ``side effect''. In many cases, a function's primary purpose is to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2605 create a side effect.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2606 @end itemize
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2607
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2608 @node Error Message Exercises, , Summary, List Processing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2609 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2610 @section Exercises
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2611
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2612 A few simple exercises:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2613
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2614 @itemize @bullet
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2615 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2616 Generate an error message by evaluating an appropriate symbol that is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2617 not within parentheses.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2618
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2619 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2620 Generate an error message by evaluating an appropriate symbol that is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2621 between parentheses.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2622
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2623 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2624 Create a counter that increments by two rather than one.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2625
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2626 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2627 Write an expression that prints a message in the echo area when
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2628 evaluated.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2629 @end itemize
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2630
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2631 @node Practicing Evaluation, Writing Defuns, List Processing, Top
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2632 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2633 @chapter Practicing Evaluation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2634 @cindex Practicing evaluation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2635 @cindex Evaluation practice
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2636
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2637 Before learning how to write a function definition in Emacs Lisp, it is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2638 useful to spend a little time evaluating various expressions that have
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2639 already been written. These expressions will be lists with the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2640 functions as their first (and often only) element. Since some of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2641 functions associated with buffers are both simple and interesting, we
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2642 will start with those. In this section, we will evaluate a few of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2643 these. In another section, we will study the code of several other
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2644 buffer-related functions, to see how they were written.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2645
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2646 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2647 * How to Evaluate:: Typing editing commands or @kbd{C-x C-e}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2648 causes evaluation.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2649 * Buffer Names:: Buffers and files are different.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2650 * Getting Buffers:: Getting a buffer itself, not merely its name.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2651 * Switching Buffers:: How to change to another buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2652 * Buffer Size & Locations:: Where point is located and the size of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2653 the buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2654 * Evaluation Exercise::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2655 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2656
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2657 @node How to Evaluate, Buffer Names, Practicing Evaluation, Practicing Evaluation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2658 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2659 @unnumberedsec How to Evaluate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2660 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2661
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2662 @i{Whenever you give an editing command} to Emacs Lisp, such as the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2663 command to move the cursor or to scroll the screen, @i{you are evaluating
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2664 an expression,} the first element of which is a function. @i{This is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2665 how Emacs works.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2666
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2667 @cindex @samp{interactive function} defined
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2668 @cindex @samp{command} defined
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2669 When you type keys, you cause the Lisp interpreter to evaluate an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2670 expression and that is how you get your results. Even typing plain text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2671 involves evaluating an Emacs Lisp function, in this case, one that uses
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2672 @code{self-insert-command}, which simply inserts the character you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2673 typed. The functions you evaluate by typing keystrokes are called
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2674 @dfn{interactive} functions, or @dfn{commands}; how you make a function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2675 interactive will be illustrated in the chapter on how to write function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2676 definitions. @xref{Interactive, , Making a Function Interactive}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2677
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2678 In addition to typing keyboard commands, we have seen a second way to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2679 evaluate an expression: by positioning the cursor after a list and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2680 typing @kbd{C-x C-e}. This is what we will do in the rest of this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2681 section. There are other ways to evaluate an expression as well; these
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2682 will be described as we come to them.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2683
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2684 Besides being used for practicing evaluation, the functions shown in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2685 next few sections are important in their own right. A study of these
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2686 functions makes clear the distinction between buffers and files, how to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2687 switch to a buffer, and how to determine a location within it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2688
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2689 @node Buffer Names, Getting Buffers, How to Evaluate, Practicing Evaluation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2690 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2691 @section Buffer Names
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2692 @findex buffer-name
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2693 @findex buffer-file-name
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2694
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2695 The two functions, @code{buffer-name} and @code{buffer-file-name}, show
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2696 the difference between a file and a buffer. When you evaluate the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2697 following expression, @code{(buffer-name)}, the name of the buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2698 appears in the echo area. When you evaluate @code{(buffer-file-name)},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2699 the name of the file to which the buffer refers appears in the echo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2700 area. Usually, the name returned by @code{(buffer-name)} is the same as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2701 the name of the file to which it refers, and the name returned by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2702 @code{(buffer-file-name)} is the full path-name of the file.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2703
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2704 A file and a buffer are two different entities. A file is information
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2705 recorded permanently in the computer (unless you delete it). A buffer,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2706 on the other hand, is information inside of Emacs that will vanish at
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2707 the end of the editing session (or when you kill the buffer). Usually,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2708 a buffer contains information that you have copied from a file; we say
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2709 the buffer is @dfn{visiting} that file. This copy is what you work on
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2710 and modify. Changes to the buffer do not change the file, until you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2711 save the buffer. When you save the buffer, the buffer is copied to the file
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2712 and is thus saved permanently.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2713
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2714 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2715 If you are reading this in Info inside of GNU Emacs, you can evaluate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2716 each of the following expressions by positioning the cursor after it and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2717 typing @kbd{C-x C-e}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2718
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2719 @example
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2720 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2721 (buffer-name)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2722
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2723 (buffer-file-name)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2724 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2725 @end example
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2726
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2727 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2728 When I do this in Info, the value returned by evaluating
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2729 @code{(buffer-name)} is @file{"*info*"}, and the value returned by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2730 evaluating @code{(buffer-file-name)} is @file{nil}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2731
98525
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
2732 On the other hand, while I am writing this document, the value
83955
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2733 returned by evaluating @code{(buffer-name)} is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2734 @file{"introduction.texinfo"}, and the value returned by evaluating
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2735 @code{(buffer-file-name)} is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2736 @file{"/gnu/work/intro/introduction.texinfo"}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2737
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2738 @cindex @code{nil}, history of word
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2739 The former is the name of the buffer and the latter is the name of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2740 file. In Info, the buffer name is @file{"*info*"}. Info does not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2741 point to any file, so the result of evaluating
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2742 @code{(buffer-file-name)} is @file{nil}. The symbol @code{nil} is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2743 from the Latin word for `nothing'; in this case, it means that the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2744 buffer is not associated with any file. (In Lisp, @code{nil} is also
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2745 used to mean `false' and is a synonym for the empty list, @code{()}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2746
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2747 When I am writing, the name of my buffer is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2748 @file{"introduction.texinfo"}. The name of the file to which it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2749 points is @file{"/gnu/work/intro/introduction.texinfo"}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2750
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2751 (In the expressions, the parentheses tell the Lisp interpreter to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2752 treat @w{@code{buffer-name}} and @w{@code{buffer-file-name}} as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2753 functions; without the parentheses, the interpreter would attempt to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2754 evaluate the symbols as variables. @xref{Variables}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2755
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2756 In spite of the distinction between files and buffers, you will often
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2757 find that people refer to a file when they mean a buffer and vice-verse.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2758 Indeed, most people say, ``I am editing a file,'' rather than saying,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2759 ``I am editing a buffer which I will soon save to a file.'' It is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2760 almost always clear from context what people mean. When dealing with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2761 computer programs, however, it is important to keep the distinction in mind,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2762 since the computer is not as smart as a person.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2763
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2764 @cindex Buffer, history of word
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2765 The word `buffer', by the way, comes from the meaning of the word as a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2766 cushion that deadens the force of a collision. In early computers, a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2767 buffer cushioned the interaction between files and the computer's
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2768 central processing unit. The drums or tapes that held a file and the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2769 central processing unit were pieces of equipment that were very
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2770 different from each other, working at their own speeds, in spurts. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2771 buffer made it possible for them to work together effectively.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2772 Eventually, the buffer grew from being an intermediary, a temporary
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2773 holding place, to being the place where work is done. This
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2774 transformation is rather like that of a small seaport that grew into a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2775 great city: once it was merely the place where cargo was warehoused
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2776 temporarily before being loaded onto ships; then it became a business
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2777 and cultural center in its own right.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2778
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2779 Not all buffers are associated with files. For example, a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2780 @file{*scratch*} buffer does not visit any file. Similarly, a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2781 @file{*Help*} buffer is not associated with any file.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2782
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2783 In the old days, when you lacked a @file{~/.emacs} file and started an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2784 Emacs session by typing the command @code{emacs} alone, without naming
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2785 any files, Emacs started with the @file{*scratch*} buffer visible.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2786 Nowadays, you will see a splash screen. You can follow one of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2787 commands suggested on the splash screen, visit a file, or press the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2788 spacebar to reach the @file{*scratch*} buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2789
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2790 If you switch to the @file{*scratch*} buffer, type
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2791 @code{(buffer-name)}, position the cursor after it, and then type
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2792 @kbd{C-x C-e} to evaluate the expression. The name @code{"*scratch*"}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2793 will be returned and will appear in the echo area. @code{"*scratch*"}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2794 is the name of the buffer. When you type @code{(buffer-file-name)} in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2795 the @file{*scratch*} buffer and evaluate that, @code{nil} will appear
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2796 in the echo area, just as it does when you evaluate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2797 @code{(buffer-file-name)} in Info.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2798
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2799 Incidentally, if you are in the @file{*scratch*} buffer and want the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2800 value returned by an expression to appear in the @file{*scratch*}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2801 buffer itself rather than in the echo area, type @kbd{C-u C-x C-e}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2802 instead of @kbd{C-x C-e}. This causes the value returned to appear
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2803 after the expression. The buffer will look like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2804
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2805 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2806 (buffer-name)"*scratch*"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2807 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2808
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2809 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2810 You cannot do this in Info since Info is read-only and it will not allow
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2811 you to change the contents of the buffer. But you can do this in any
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2812 buffer you can edit; and when you write code or documentation (such as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2813 this book), this feature is very useful.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2814
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2815 @node Getting Buffers, Switching Buffers, Buffer Names, Practicing Evaluation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2816 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2817 @section Getting Buffers
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2818 @findex current-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2819 @findex other-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2820 @cindex Getting a buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2821
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2822 The @code{buffer-name} function returns the @emph{name} of the buffer;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2823 to get the buffer @emph{itself}, a different function is needed: the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2824 @code{current-buffer} function. If you use this function in code, what
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2825 you get is the buffer itself.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2826
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2827 A name and the object or entity to which the name refers are different
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2828 from each other. You are not your name. You are a person to whom
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2829 others refer by name. If you ask to speak to George and someone hands you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2830 a card with the letters @samp{G}, @samp{e}, @samp{o}, @samp{r},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2831 @samp{g}, and @samp{e} written on it, you might be amused, but you would
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2832 not be satisfied. You do not want to speak to the name, but to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2833 person to whom the name refers. A buffer is similar: the name of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2834 scratch buffer is @file{*scratch*}, but the name is not the buffer. To
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2835 get a buffer itself, you need to use a function such as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2836 @code{current-buffer}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2837
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2838 However, there is a slight complication: if you evaluate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2839 @code{current-buffer} in an expression on its own, as we will do here,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2840 what you see is a printed representation of the name of the buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2841 without the contents of the buffer. Emacs works this way for two
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2842 reasons: the buffer may be thousands of lines long---too long to be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2843 conveniently displayed; and, another buffer may have the same contents
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2844 but a different name, and it is important to distinguish between them.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2845
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2846 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2847 Here is an expression containing the function:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2848
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2849 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2850 (current-buffer)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2851 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2852
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2853 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2854 If you evaluate this expression in Info in Emacs in the usual way,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2855 @file{#<buffer *info*>} will appear in the echo area. The special
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2856 format indicates that the buffer itself is being returned, rather than
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2857 just its name.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2858
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2859 Incidentally, while you can type a number or symbol into a program, you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2860 cannot do that with the printed representation of a buffer: the only way
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2861 to get a buffer itself is with a function such as @code{current-buffer}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2862
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2863 A related function is @code{other-buffer}. This returns the most
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2864 recently selected buffer other than the one you are in currently, not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2865 a printed representation of its name. If you have recently switched
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2866 back and forth from the @file{*scratch*} buffer, @code{other-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2867 will return that buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2868
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2869 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2870 You can see this by evaluating the expression:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2871
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2872 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2873 (other-buffer)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2874 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2875
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2876 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2877 You should see @file{#<buffer *scratch*>} appear in the echo area, or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2878 the name of whatever other buffer you switched back from most
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2879 recently@footnote{Actually, by default, if the buffer from which you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2880 just switched is visible to you in another window, @code{other-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2881 will choose the most recent buffer that you cannot see; this is a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2882 subtlety that I often forget.}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2883
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2884 @node Switching Buffers, Buffer Size & Locations, Getting Buffers, Practicing Evaluation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2885 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2886 @section Switching Buffers
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2887 @findex switch-to-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2888 @findex set-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2889 @cindex Switching to a buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2890
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2891 The @code{other-buffer} function actually provides a buffer when it is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2892 used as an argument to a function that requires one. We can see this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2893 by using @code{other-buffer} and @code{switch-to-buffer} to switch to a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2894 different buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2895
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2896 But first, a brief introduction to the @code{switch-to-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2897 function. When you switched back and forth from Info to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2898 @file{*scratch*} buffer to evaluate @code{(buffer-name)}, you most
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2899 likely typed @kbd{C-x b} and then typed @file{*scratch*}@footnote{Or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2900 rather, to save typing, you probably only typed @kbd{RET} if the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2901 default buffer was @file{*scratch*}, or if it was different, then you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2902 typed just part of the name, such as @code{*sc}, pressed your
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2903 @kbd{TAB} key to cause it to expand to the full name, and then typed
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2904 your @kbd{RET} key.} when prompted in the minibuffer for the name of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2905 the buffer to which you wanted to switch. The keystrokes, @kbd{C-x
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2906 b}, cause the Lisp interpreter to evaluate the interactive function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2907 @code{switch-to-buffer}. As we said before, this is how Emacs works:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2908 different keystrokes call or run different functions. For example,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2909 @kbd{C-f} calls @code{forward-char}, @kbd{M-e} calls
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2910 @code{forward-sentence}, and so on.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2911
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2912 By writing @code{switch-to-buffer} in an expression, and giving it a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2913 buffer to switch to, we can switch buffers just the way @kbd{C-x b}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2914 does.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2915
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2916 @need 1000
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2917 Here is the Lisp expression:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2918
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2919 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2920 (switch-to-buffer (other-buffer))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2921 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2922
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2923 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2924 The symbol @code{switch-to-buffer} is the first element of the list,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2925 so the Lisp interpreter will treat it as a function and carry out the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2926 instructions that are attached to it. But before doing that, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2927 interpreter will note that @code{other-buffer} is inside parentheses
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2928 and work on that symbol first. @code{other-buffer} is the first (and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2929 in this case, the only) element of this list, so the Lisp interpreter
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2930 calls or runs the function. It returns another buffer. Next, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2931 interpreter runs @code{switch-to-buffer}, passing to it, as an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2932 argument, the other buffer, which is what Emacs will switch to. If
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2933 you are reading this in Info, try this now. Evaluate the expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2934 (To get back, type @kbd{C-x b @key{RET}}.)@footnote{Remember, this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2935 expression will move you to your most recent other buffer that you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2936 cannot see. If you really want to go to your most recently selected
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2937 buffer, even if you can still see it, you need to evaluate the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2938 following more complex expression:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2939
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2940 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2941 (switch-to-buffer (other-buffer (current-buffer) t))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2942 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2943
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2944 @c noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2945 In this case, the first argument to @code{other-buffer} tells it which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2946 buffer to skip---the current one---and the second argument tells
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2947 @code{other-buffer} it is OK to switch to a visible buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2948 In regular use, @code{switch-to-buffer} takes you to an invisible
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2949 window since you would most likely use @kbd{C-x o} (@code{other-window})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2950 to go to another visible buffer.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2951
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2952 In the programming examples in later sections of this document, you will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2953 see the function @code{set-buffer} more often than
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2954 @code{switch-to-buffer}. This is because of a difference between
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2955 computer programs and humans: humans have eyes and expect to see the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2956 buffer on which they are working on their computer terminals. This is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2957 so obvious, it almost goes without saying. However, programs do not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2958 have eyes. When a computer program works on a buffer, that buffer does
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2959 not need to be visible on the screen.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2960
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2961 @code{switch-to-buffer} is designed for humans and does two different
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2962 things: it switches the buffer to which Emacs' attention is directed; and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2963 it switches the buffer displayed in the window to the new buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2964 @code{set-buffer}, on the other hand, does only one thing: it switches
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2965 the attention of the computer program to a different buffer. The buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2966 on the screen remains unchanged (of course, normally nothing happens
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2967 there until the command finishes running).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2968
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2969 @cindex @samp{call} defined
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2970 Also, we have just introduced another jargon term, the word @dfn{call}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2971 When you evaluate a list in which the first symbol is a function, you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2972 are calling that function. The use of the term comes from the notion of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2973 the function as an entity that can do something for you if you `call'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2974 it---just as a plumber is an entity who can fix a leak if you call him
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2975 or her.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2976
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2977 @node Buffer Size & Locations, Evaluation Exercise, Switching Buffers, Practicing Evaluation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2978 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2979 @section Buffer Size and the Location of Point
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2980 @cindex Size of buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2981 @cindex Buffer size
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2982 @cindex Point location
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2983 @cindex Location of point
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2984
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2985 Finally, let's look at several rather simple functions,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2986 @code{buffer-size}, @code{point}, @code{point-min}, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2987 @code{point-max}. These give information about the size of a buffer and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2988 the location of point within it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2989
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2990 The function @code{buffer-size} tells you the size of the current
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2991 buffer; that is, the function returns a count of the number of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2992 characters in the buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2993
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2994 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2995 (buffer-size)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2996 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2997
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2998 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2999 You can evaluate this in the usual way, by positioning the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3000 cursor after the expression and typing @kbd{C-x C-e}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3001
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3002 @cindex @samp{point} defined
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3003 In Emacs, the current position of the cursor is called @dfn{point}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3004 The expression @code{(point)} returns a number that tells you where the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3005 cursor is located as a count of the number of characters from the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3006 beginning of the buffer up to point.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3007
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3008 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3009 You can see the character count for point in this buffer by evaluating
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3010 the following expression in the usual way:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3011
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3012 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3013 (point)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3014 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3015
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3016 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3017 As I write this, the value of @code{point} is 65724. The @code{point}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3018 function is frequently used in some of the examples later in this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3019 book.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3020
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3021 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3022 The value of point depends, of course, on its location within the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3023 buffer. If you evaluate point in this spot, the number will be larger:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3024
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3025 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3026 (point)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3027 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3028
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3029 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3030 For me, the value of point in this location is 66043, which means that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3031 there are 319 characters (including spaces) between the two
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3032 expressions. (Doubtless, you will see different numbers, since I will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3033 have edited this since I first evaluated point.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3034
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3035 @cindex @samp{narrowing} defined
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3036 The function @code{point-min} is somewhat similar to @code{point}, but
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3037 it returns the value of the minimum permissible value of point in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3038 current buffer. This is the number 1 unless @dfn{narrowing} is in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3039 effect. (Narrowing is a mechanism whereby you can restrict yourself,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3040 or a program, to operations on just a part of a buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3041 @xref{Narrowing & Widening, , Narrowing and Widening}.) Likewise, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3042 function @code{point-max} returns the value of the maximum permissible
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3043 value of point in the current buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3044
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3045 @node Evaluation Exercise, , Buffer Size & Locations, Practicing Evaluation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3046 @section Exercise
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3047
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3048 Find a file with which you are working and move towards its middle.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3049 Find its buffer name, file name, length, and your position in the file.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3050
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3051 @node Writing Defuns, Buffer Walk Through, Practicing Evaluation, Top
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3052 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3053 @chapter How To Write Function Definitions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3054 @cindex Definition writing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3055 @cindex Function definition writing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3056 @cindex Writing a function definition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3057
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3058 When the Lisp interpreter evaluates a list, it looks to see whether the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3059 first symbol on the list has a function definition attached to it; or,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3060 put another way, whether the symbol points to a function definition. If
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3061 it does, the computer carries out the instructions in the definition. A
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3062 symbol that has a function definition is called, simply, a function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3063 (although, properly speaking, the definition is the function and the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3064 symbol refers to it.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3065
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3066 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3067 * Primitive Functions::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3068 * defun:: The @code{defun} special form.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3069 * Install:: Install a function definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3070 * Interactive:: Making a function interactive.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3071 * Interactive Options:: Different options for @code{interactive}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3072 * Permanent Installation:: Installing code permanently.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3073 * let:: Creating and initializing local variables.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3074 * if:: What if?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3075 * else:: If--then--else expressions.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3076 * Truth & Falsehood:: What Lisp considers false and true.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3077 * save-excursion:: Keeping track of point, mark, and buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3078 * Review::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3079 * defun Exercises::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3080 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3081
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3082 @node Primitive Functions, defun, Writing Defuns, Writing Defuns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3083 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3084 @unnumberedsec An Aside about Primitive Functions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3085 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3086 @cindex Primitive functions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3087 @cindex Functions, primitive
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3088
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3089 @cindex C language primitives
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3090 @cindex Primitives written in C
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3091 All functions are defined in terms of other functions, except for a few
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3092 @dfn{primitive} functions that are written in the C programming
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3093 language. When you write functions' definitions, you will write them in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3094 Emacs Lisp and use other functions as your building blocks. Some of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3095 functions you will use will themselves be written in Emacs Lisp (perhaps
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3096 by you) and some will be primitives written in C. The primitive
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3097 functions are used exactly like those written in Emacs Lisp and behave
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3098 like them. They are written in C so we can easily run GNU Emacs on any
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3099 computer that has sufficient power and can run C.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3100
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3101 Let me re-emphasize this: when you write code in Emacs Lisp, you do not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3102 distinguish between the use of functions written in C and the use of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3103 functions written in Emacs Lisp. The difference is irrelevant. I
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3104 mention the distinction only because it is interesting to know. Indeed,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3105 unless you investigate, you won't know whether an already-written
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3106 function is written in Emacs Lisp or C.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3107
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3108 @node defun, Install, Primitive Functions, Writing Defuns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3109 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3110 @section The @code{defun} Special Form
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3111 @findex defun
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3112 @cindex Special form of @code{defun}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3113
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3114 @cindex @samp{function definition} defined
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3115 In Lisp, a symbol such as @code{mark-whole-buffer} has code attached to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3116 it that tells the computer what to do when the function is called.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3117 This code is called the @dfn{function definition} and is created by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3118 evaluating a Lisp expression that starts with the symbol @code{defun}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3119 (which is an abbreviation for @emph{define function}). Because
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3120 @code{defun} does not evaluate its arguments in the usual way, it is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3121 called a @dfn{special form}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3122
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3123 In subsequent sections, we will look at function definitions from the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3124 Emacs source code, such as @code{mark-whole-buffer}. In this section,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3125 we will describe a simple function definition so you can see how it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3126 looks. This function definition uses arithmetic because it makes for a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3127 simple example. Some people dislike examples using arithmetic; however,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3128 if you are such a person, do not despair. Hardly any of the code we
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3129 will study in the remainder of this introduction involves arithmetic or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3130 mathematics. The examples mostly involve text in one way or another.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3131
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3132 A function definition has up to five parts following the word
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3133 @code{defun}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3134
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3135 @enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3136 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3137 The name of the symbol to which the function definition should be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3138 attached.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3139
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3140 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3141 A list of the arguments that will be passed to the function. If no
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3142 arguments will be passed to the function, this is an empty list,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3143 @code{()}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3144
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3145 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3146 Documentation describing the function. (Technically optional, but
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3147 strongly recommended.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3148
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3149 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3150 Optionally, an expression to make the function interactive so you can
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3151 use it by typing @kbd{M-x} and then the name of the function; or by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3152 typing an appropriate key or keychord.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3153
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3154 @cindex @samp{body} defined
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3155 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3156 The code that instructs the computer what to do: the @dfn{body} of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3157 function definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3158 @end enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3159
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3160 It is helpful to think of the five parts of a function definition as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3161 being organized in a template, with slots for each part:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3162
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3163 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3164 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3165 (defun @var{function-name} (@var{arguments}@dots{})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3166 "@var{optional-documentation}@dots{}"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3167 (interactive @var{argument-passing-info}) ; @r{optional}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3168 @var{body}@dots{})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3169 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3170 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3171
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3172 As an example, here is the code for a function that multiplies its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3173 argument by 7. (This example is not interactive. @xref{Interactive,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3174 , Making a Function Interactive}, for that information.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3175
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3176 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3177 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3178 (defun multiply-by-seven (number)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3179 "Multiply NUMBER by seven."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3180 (* 7 number))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3181 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3182 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3183
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3184 This definition begins with a parenthesis and the symbol @code{defun},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3185 followed by the name of the function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3186
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3187 @cindex @samp{argument list} defined
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3188 The name of the function is followed by a list that contains the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3189 arguments that will be passed to the function. This list is called
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3190 the @dfn{argument list}. In this example, the list has only one
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3191 element, the symbol, @code{number}. When the function is used, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3192 symbol will be bound to the value that is used as the argument to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3193 function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3194
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3195 Instead of choosing the word @code{number} for the name of the argument,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3196 I could have picked any other name. For example, I could have chosen
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3197 the word @code{multiplicand}. I picked the word `number' because it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3198 tells what kind of value is intended for this slot; but I could just as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3199 well have chosen the word `multiplicand' to indicate the role that the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3200 value placed in this slot will play in the workings of the function. I
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3201 could have called it @code{foogle}, but that would have been a bad
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3202 choice because it would not tell humans what it means. The choice of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3203 name is up to the programmer and should be chosen to make the meaning of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3204 the function clear.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3205
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3206 Indeed, you can choose any name you wish for a symbol in an argument
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3207 list, even the name of a symbol used in some other function: the name
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3208 you use in an argument list is private to that particular definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3209 In that definition, the name refers to a different entity than any use
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3210 of the same name outside the function definition. Suppose you have a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3211 nick-name `Shorty' in your family; when your family members refer to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3212 `Shorty', they mean you. But outside your family, in a movie, for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3213 example, the name `Shorty' refers to someone else. Because a name in an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3214 argument list is private to the function definition, you can change the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3215 value of such a symbol inside the body of a function without changing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3216 its value outside the function. The effect is similar to that produced
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3217 by a @code{let} expression. (@xref{let, , @code{let}}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3218
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3219 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3220 Note also that we discuss the word `number' in two different ways: as a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3221 symbol that appears in the code, and as the name of something that will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3222 be replaced by a something else during the evaluation of the function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3223 In the first case, @code{number} is a symbol, not a number; it happens
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3224 that within the function, it is a variable who value is the number in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3225 question, but our primary interest in it is as a symbol. On the other
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3226 hand, when we are talking about the function, our interest is that we
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3227 will substitute a number for the word @var{number}. To keep this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3228 distinction clear, we use different typography for the two
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3229 circumstances. When we talk about this function, or about how it works,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3230 we refer to this number by writing @var{number}. In the function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3231 itself, we refer to it by writing @code{number}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3232 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3233
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3234 The argument list is followed by the documentation string that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3235 describes the function. This is what you see when you type
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3236 @w{@kbd{C-h f}} and the name of a function. Incidentally, when you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3237 write a documentation string like this, you should make the first line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3238 a complete sentence since some commands, such as @code{apropos}, print
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3239 only the first line of a multi-line documentation string. Also, you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3240 should not indent the second line of a documentation string, if you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3241 have one, because that looks odd when you use @kbd{C-h f}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3242 (@code{describe-function}). The documentation string is optional, but
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3243 it is so useful, it should be included in almost every function you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3244 write.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3245
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3246 @findex * @r{(multiplication)}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3247 The third line of the example consists of the body of the function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3248 definition. (Most functions' definitions, of course, are longer than
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3249 this.) In this function, the body is the list, @code{(* 7 number)}, which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3250 says to multiply the value of @var{number} by 7. (In Emacs Lisp,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3251 @code{*} is the function for multiplication, just as @code{+} is the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3252 function for addition.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3253
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3254 When you use the @code{multiply-by-seven} function, the argument
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3255 @code{number} evaluates to the actual number you want used. Here is an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3256 example that shows how @code{multiply-by-seven} is used; but don't try
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3257 to evaluate this yet!
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3258
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3259 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3260 (multiply-by-seven 3)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3261 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3262
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3263 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3264 The symbol @code{number}, specified in the function definition in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3265 next section, is given or ``bound to'' the value 3 in the actual use of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3266 the function. Note that although @code{number} was inside parentheses
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3267 in the function definition, the argument passed to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3268 @code{multiply-by-seven} function is not in parentheses. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3269 parentheses are written in the function definition so the computer can
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3270 figure out where the argument list ends and the rest of the function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3271 definition begins.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3272
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3273 If you evaluate this example, you are likely to get an error message.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3274 (Go ahead, try it!) This is because we have written the function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3275 definition, but not yet told the computer about the definition---we have
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3276 not yet installed (or `loaded') the function definition in Emacs.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3277 Installing a function is the process that tells the Lisp interpreter the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3278 definition of the function. Installation is described in the next
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3279 section.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3280
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3281 @node Install, Interactive, defun, Writing Defuns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3282 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3283 @section Install a Function Definition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3284 @cindex Install a Function Definition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3285 @cindex Definition installation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3286 @cindex Function definition installation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3287
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3288 If you are reading this inside of Info in Emacs, you can try out the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3289 @code{multiply-by-seven} function by first evaluating the function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3290 definition and then evaluating @code{(multiply-by-seven 3)}. A copy of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3291 the function definition follows. Place the cursor after the last
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3292 parenthesis of the function definition and type @kbd{C-x C-e}. When you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3293 do this, @code{multiply-by-seven} will appear in the echo area. (What
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3294 this means is that when a function definition is evaluated, the value it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3295 returns is the name of the defined function.) At the same time, this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3296 action installs the function definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3297
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3298 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3299 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3300 (defun multiply-by-seven (number)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3301 "Multiply NUMBER by seven."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3302 (* 7 number))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3303 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3304 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3305
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3306 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3307 By evaluating this @code{defun}, you have just installed
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3308 @code{multiply-by-seven} in Emacs. The function is now just as much a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3309 part of Emacs as @code{forward-word} or any other editing function you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3310 use. (@code{multiply-by-seven} will stay installed until you quit
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3311 Emacs. To reload code automatically whenever you start Emacs, see
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3312 @ref{Permanent Installation, , Installing Code Permanently}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3313
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3314 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3315 * Effect of installation::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3316 * Change a defun:: How to change a function definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3317 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3318
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3319 @node Effect of installation, Change a defun, Install, Install
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3320 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3321 @unnumberedsubsec The effect of installation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3322 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3323
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3324 You can see the effect of installing @code{multiply-by-seven} by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3325 evaluating the following sample. Place the cursor after the following
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3326 expression and type @kbd{C-x C-e}. The number 21 will appear in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3327 echo area.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3328
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3329 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3330 (multiply-by-seven 3)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3331 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3332
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3333 If you wish, you can read the documentation for the function by typing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3334 @kbd{C-h f} (@code{describe-function}) and then the name of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3335 function, @code{multiply-by-seven}. When you do this, a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3336 @file{*Help*} window will appear on your screen that says:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3337
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3338 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3339 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3340 multiply-by-seven is a Lisp function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3341 (multiply-by-seven NUMBER)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3342
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3343 Multiply NUMBER by seven.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3344 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3345 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3346
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3347 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3348 (To return to a single window on your screen, type @kbd{C-x 1}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3349
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3350 @node Change a defun, , Effect of installation, Install
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3351 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3352 @subsection Change a Function Definition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3353 @cindex Changing a function definition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3354 @cindex Function definition, how to change
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3355 @cindex Definition, how to change
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3356
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3357 If you want to change the code in @code{multiply-by-seven}, just rewrite
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3358 it. To install the new version in place of the old one, evaluate the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3359 function definition again. This is how you modify code in Emacs. It is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3360 very simple.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3361
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3362 As an example, you can change the @code{multiply-by-seven} function to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3363 add the number to itself seven times instead of multiplying the number
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3364 by seven. It produces the same answer, but by a different path. At
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3365 the same time, we will add a comment to the code; a comment is text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3366 that the Lisp interpreter ignores, but that a human reader may find
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3367 useful or enlightening. The comment is that this is the ``second
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3368 version''.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3369
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3370 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3371 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3372 (defun multiply-by-seven (number) ; @r{Second version.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3373 "Multiply NUMBER by seven."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3374 (+ number number number number number number number))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3375 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3376 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3377
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3378 @cindex Comments in Lisp code
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3379 The comment follows a semicolon, @samp{;}. In Lisp, everything on a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3380 line that follows a semicolon is a comment. The end of the line is the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3381 end of the comment. To stretch a comment over two or more lines, begin
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3382 each line with a semicolon.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3383
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3384 @xref{Beginning a .emacs File, , Beginning a @file{.emacs}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3385 File}, and @ref{Comments, , Comments, elisp, The GNU Emacs Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3386 Reference Manual}, for more about comments.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3387
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3388 You can install this version of the @code{multiply-by-seven} function by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3389 evaluating it in the same way you evaluated the first function: place
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3390 the cursor after the last parenthesis and type @kbd{C-x C-e}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3391
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3392 In summary, this is how you write code in Emacs Lisp: you write a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3393 function; install it; test it; and then make fixes or enhancements and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3394 install it again.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3395
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3396 @node Interactive, Interactive Options, Install, Writing Defuns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3397 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3398 @section Make a Function Interactive
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3399 @cindex Interactive functions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3400 @findex interactive
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3401
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3402 You make a function interactive by placing a list that begins with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3403 the special form @code{interactive} immediately after the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3404 documentation. A user can invoke an interactive function by typing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3405 @kbd{M-x} and then the name of the function; or by typing the keys to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3406 which it is bound, for example, by typing @kbd{C-n} for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3407 @code{next-line} or @kbd{C-x h} for @code{mark-whole-buffer}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3408
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3409 Interestingly, when you call an interactive function interactively,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3410 the value returned is not automatically displayed in the echo area.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3411 This is because you often call an interactive function for its side
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3412 effects, such as moving forward by a word or line, and not for the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3413 value returned. If the returned value were displayed in the echo area
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3414 each time you typed a key, it would be very distracting.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3415
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3416 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3417 * Interactive multiply-by-seven:: An overview.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3418 * multiply-by-seven in detail:: The interactive version.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3419 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3420
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3421 @node Interactive multiply-by-seven, multiply-by-seven in detail, Interactive, Interactive
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3422 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3423 @unnumberedsubsec An Interactive @code{multiply-by-seven}, An Overview
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3424 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3425
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3426 Both the use of the special form @code{interactive} and one way to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3427 display a value in the echo area can be illustrated by creating an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3428 interactive version of @code{multiply-by-seven}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3429
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3430 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3431 Here is the code:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3432
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3433 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3434 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3435 (defun multiply-by-seven (number) ; @r{Interactive version.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3436 "Multiply NUMBER by seven."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3437 (interactive "p")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3438 (message "The result is %d" (* 7 number)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3439 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3440 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3441
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3442 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3443 You can install this code by placing your cursor after it and typing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3444 @kbd{C-x C-e}. The name of the function will appear in your echo area.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3445 Then, you can use this code by typing @kbd{C-u} and a number and then
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3446 typing @kbd{M-x multiply-by-seven} and pressing @key{RET}. The phrase
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3447 @samp{The result is @dots{}} followed by the product will appear in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3448 echo area.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3449
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3450 Speaking more generally, you invoke a function like this in either of two
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3451 ways:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3452
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3453 @enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3454 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3455 By typing a prefix argument that contains the number to be passed, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3456 then typing @kbd{M-x} and the name of the function, as with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3457 @kbd{C-u 3 M-x forward-sentence}; or,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3458
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3459 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3460 By typing whatever key or keychord the function is bound to, as with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3461 @kbd{C-u 3 M-e}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3462 @end enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3463
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3464 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3465 Both the examples just mentioned work identically to move point forward
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3466 three sentences. (Since @code{multiply-by-seven} is not bound to a key,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3467 it could not be used as an example of key binding.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3468
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3469 (@xref{Keybindings, , Some Keybindings}, to learn how to bind a command
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3470 to a key.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3471
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3472 A prefix argument is passed to an interactive function by typing the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3473 @key{META} key followed by a number, for example, @kbd{M-3 M-e}, or by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3474 typing @kbd{C-u} and then a number, for example, @kbd{C-u 3 M-e} (if you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3475 type @kbd{C-u} without a number, it defaults to 4).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3476
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3477 @node multiply-by-seven in detail, , Interactive multiply-by-seven, Interactive
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3478 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3479 @subsection An Interactive @code{multiply-by-seven}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3480
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3481 Let's look at the use of the special form @code{interactive} and then at
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3482 the function @code{message} in the interactive version of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3483 @code{multiply-by-seven}. You will recall that the function definition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3484 looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3485
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3486 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3487 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3488 (defun multiply-by-seven (number) ; @r{Interactive version.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3489 "Multiply NUMBER by seven."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3490 (interactive "p")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3491 (message "The result is %d" (* 7 number)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3492 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3493 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3494
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3495 In this function, the expression, @code{(interactive "p")}, is a list of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3496 two elements. The @code{"p"} tells Emacs to pass the prefix argument to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3497 the function and use its value for the argument of the function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3498
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3499 @need 1000
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3500 The argument will be a number. This means that the symbol
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3501 @code{number} will be bound to a number in the line:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3502
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3503 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3504 (message "The result is %d" (* 7 number))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3505 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3506
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3507 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3508 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3509 For example, if your prefix argument is 5, the Lisp interpreter will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3510 evaluate the line as if it were:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3511
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3512 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3513 (message "The result is %d" (* 7 5))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3514 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3515
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3516 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3517 (If you are reading this in GNU Emacs, you can evaluate this expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3518 yourself.) First, the interpreter will evaluate the inner list, which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3519 is @code{(* 7 5)}. This returns a value of 35. Next, it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3520 will evaluate the outer list, passing the values of the second and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3521 subsequent elements of the list to the function @code{message}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3522
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3523 As we have seen, @code{message} is an Emacs Lisp function especially
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3524 designed for sending a one line message to a user. (@xref{message, ,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3525 The @code{message} function}.) In summary, the @code{message}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3526 function prints its first argument in the echo area as is, except for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3527 occurrences of @samp{%d} or @samp{%s} (and various other %-sequences
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3528 which we have not mentioned). When it sees a control sequence, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3529 function looks to the second or subsequent arguments and prints the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3530 value of the argument in the location in the string where the control
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3531 sequence is located.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3532
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3533 In the interactive @code{multiply-by-seven} function, the control string
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3534 is @samp{%d}, which requires a number, and the value returned by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3535 evaluating @code{(* 7 5)} is the number 35. Consequently, the number 35
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3536 is printed in place of the @samp{%d} and the message is @samp{The result
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3537 is 35}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3538
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3539 (Note that when you call the function @code{multiply-by-seven}, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3540 message is printed without quotes, but when you call @code{message}, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3541 text is printed in double quotes. This is because the value returned by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3542 @code{message} is what appears in the echo area when you evaluate an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3543 expression whose first element is @code{message}; but when embedded in a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3544 function, @code{message} prints the text as a side effect without
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3545 quotes.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3546
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3547 @node Interactive Options, Permanent Installation, Interactive, Writing Defuns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3548 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3549 @section Different Options for @code{interactive}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3550 @cindex Options for @code{interactive}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3551 @cindex Interactive options
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3552
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3553 In the example, @code{multiply-by-seven} used @code{"p"} as the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3554 argument to @code{interactive}. This argument told Emacs to interpret
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3555 your typing either @kbd{C-u} followed by a number or @key{META}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3556 followed by a number as a command to pass that number to the function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3557 as its argument. Emacs has more than twenty characters predefined for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3558 use with @code{interactive}. In almost every case, one of these
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3559 options will enable you to pass the right information interactively to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3560 a function. (@xref{Interactive Codes, , Code Characters for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3561 @code{interactive}, elisp, The GNU Emacs Lisp Reference Manual}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3562
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3563 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3564 Consider the function @code{zap-to-char}. Its interactive expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3565 is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3566
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3567 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3568 (interactive "p\ncZap to char: ")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3569 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3570
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3571 The first part of the argument to @code{interactive} is @samp{p}, with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3572 which you are already familiar. This argument tells Emacs to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3573 interpret a `prefix', as a number to be passed to the function. You
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3574 can specify a prefix either by typing @kbd{C-u} followed by a number
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3575 or by typing @key{META} followed by a number. The prefix is the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3576 number of specified characters. Thus, if your prefix is three and the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3577 specified character is @samp{x}, then you will delete all the text up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3578 to and including the third next @samp{x}. If you do not set a prefix,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3579 then you delete all the text up to and including the specified
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3580 character, but no more.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3581
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3582 The @samp{c} tells the function the name of the character to which to delete.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3583
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3584 More formally, a function with two or more arguments can have
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3585 information passed to each argument by adding parts to the string that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3586 follows @code{interactive}. When you do this, the information is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3587 passed to each argument in the same order it is specified in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3588 @code{interactive} list. In the string, each part is separated from
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3589 the next part by a @samp{\n}, which is a newline. For example, you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3590 can follow @samp{p} with a @samp{\n} and an @samp{cZap to char:@: }.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3591 This causes Emacs to pass the value of the prefix argument (if there
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3592 is one) and the character.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3593
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3594 In this case, the function definition looks like the following, where
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3595 @code{arg} and @code{char} are the symbols to which @code{interactive}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3596 binds the prefix argument and the specified character:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3597
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3598 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3599 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3600 (defun @var{name-of-function} (arg char)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3601 "@var{documentation}@dots{}"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3602 (interactive "p\ncZap to char: ")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3603 @var{body-of-function}@dots{})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3604 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3605 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3606
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3607 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3608 (The space after the colon in the prompt makes it look better when you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3609 are prompted. @xref{copy-to-buffer, , The Definition of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3610 @code{copy-to-buffer}}, for an example.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3611
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3612 When a function does not take arguments, @code{interactive} does not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3613 require any. Such a function contains the simple expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3614 @code{(interactive)}. The @code{mark-whole-buffer} function is like
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3615 this.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3616
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3617 Alternatively, if the special letter-codes are not right for your
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3618 application, you can pass your own arguments to @code{interactive} as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3619 a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3620
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3621 @xref{append-to-buffer, , The Definition of @code{append-to-buffer}},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3622 for an example. @xref{Using Interactive, , Using @code{Interactive},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3623 elisp, The GNU Emacs Lisp Reference Manual}, for a more complete
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3624 explanation about this technique.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3625
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3626 @node Permanent Installation, let, Interactive Options, Writing Defuns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3627 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3628 @section Install Code Permanently
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3629 @cindex Install code permanently
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3630 @cindex Permanent code installation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3631 @cindex Code installation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3632
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3633 When you install a function definition by evaluating it, it will stay
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3634 installed until you quit Emacs. The next time you start a new session
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3635 of Emacs, the function will not be installed unless you evaluate the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3636 function definition again.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3637
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3638 At some point, you may want to have code installed automatically
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3639 whenever you start a new session of Emacs. There are several ways of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3640 doing this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3641
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3642 @itemize @bullet
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3643 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3644 If you have code that is just for yourself, you can put the code for the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3645 function definition in your @file{.emacs} initialization file. When you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3646 start Emacs, your @file{.emacs} file is automatically evaluated and all
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3647 the function definitions within it are installed.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3648 @xref{Emacs Initialization, , Your @file{.emacs} File}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3649
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3650 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3651 Alternatively, you can put the function definitions that you want
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3652 installed in one or more files of their own and use the @code{load}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3653 function to cause Emacs to evaluate and thereby install each of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3654 functions in the files.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3655 @xref{Loading Files, , Loading Files}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3656
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3657 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3658 Thirdly, if you have code that your whole site will use, it is usual
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3659 to put it in a file called @file{site-init.el} that is loaded when
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3660 Emacs is built. This makes the code available to everyone who uses
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3661 your machine. (See the @file{INSTALL} file that is part of the Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3662 distribution.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3663 @end itemize
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3664
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3665 Finally, if you have code that everyone who uses Emacs may want, you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3666 can post it on a computer network or send a copy to the Free Software
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3667 Foundation. (When you do this, please license the code and its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3668 documentation under a license that permits other people to run, copy,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3669 study, modify, and redistribute the code and which protects you from
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3670 having your work taken from you.) If you send a copy of your code to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3671 the Free Software Foundation, and properly protect yourself and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3672 others, it may be included in the next release of Emacs. In large
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3673 part, this is how Emacs has grown over the past years, by donations.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3674
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3675 @node let, if, Permanent Installation, Writing Defuns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3676 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3677 @section @code{let}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3678 @findex let
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3679
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3680 The @code{let} expression is a special form in Lisp that you will need
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3681 to use in most function definitions.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3682
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3683 @code{let} is used to attach or bind a symbol to a value in such a way
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3684 that the Lisp interpreter will not confuse the variable with a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3685 variable of the same name that is not part of the function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3686
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3687 To understand why the @code{let} special form is necessary, consider
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3688 the situation in which you own a home that you generally refer to as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3689 `the house', as in the sentence, ``The house needs painting.'' If you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3690 are visiting a friend and your host refers to `the house', he is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3691 likely to be referring to @emph{his} house, not yours, that is, to a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3692 different house.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3693
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3694 If your friend is referring to his house and you think he is referring
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3695 to your house, you may be in for some confusion. The same thing could
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3696 happen in Lisp if a variable that is used inside of one function has
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3697 the same name as a variable that is used inside of another function,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3698 and the two are not intended to refer to the same value. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3699 @code{let} special form prevents this kind of confusion.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3700
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3701 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3702 * Prevent confusion::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3703 * Parts of let Expression::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3704 * Sample let Expression::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3705 * Uninitialized let Variables::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3706 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3707
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3708 @node Prevent confusion, Parts of let Expression, let, let
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3709 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3710 @unnumberedsubsec @code{let} Prevents Confusion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3711 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3712
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3713 @cindex @samp{local variable} defined
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3714 @cindex @samp{variable, local}, defined
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3715 The @code{let} special form prevents confusion. @code{let} creates a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3716 name for a @dfn{local variable} that overshadows any use of the same
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3717 name outside the @code{let} expression. This is like understanding
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3718 that whenever your host refers to `the house', he means his house, not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3719 yours. (Symbols used in argument lists work the same way.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3720 @xref{defun, , The @code{defun} Special Form}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3721
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3722 Local variables created by a @code{let} expression retain their value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3723 @emph{only} within the @code{let} expression itself (and within
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3724 expressions called within the @code{let} expression); the local
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3725 variables have no effect outside the @code{let} expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3726
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3727 Another way to think about @code{let} is that it is like a @code{setq}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3728 that is temporary and local. The values set by @code{let} are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3729 automatically undone when the @code{let} is finished. The setting
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3730 only affects expressions that are inside the bounds of the @code{let}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3731 expression. In computer science jargon, we would say ``the binding of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3732 a symbol is visible only in functions called in the @code{let} form;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3733 in Emacs Lisp, scoping is dynamic, not lexical.''
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3734
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3735 @code{let} can create more than one variable at once. Also,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3736 @code{let} gives each variable it creates an initial value, either a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3737 value specified by you, or @code{nil}. (In the jargon, this is called
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3738 `binding the variable to the value'.) After @code{let} has created
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3739 and bound the variables, it executes the code in the body of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3740 @code{let}, and returns the value of the last expression in the body,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3741 as the value of the whole @code{let} expression. (`Execute' is a jargon
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3742 term that means to evaluate a list; it comes from the use of the word
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3743 meaning `to give practical effect to' (@cite{Oxford English
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3744 Dictionary}). Since you evaluate an expression to perform an action,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3745 `execute' has evolved as a synonym to `evaluate'.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3746
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3747 @node Parts of let Expression, Sample let Expression, Prevent confusion, let
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3748 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3749 @subsection The Parts of a @code{let} Expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3750 @cindex @code{let} expression, parts of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3751 @cindex Parts of @code{let} expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3752
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3753 @cindex @samp{varlist} defined
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3754 A @code{let} expression is a list of three parts. The first part is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3755 the symbol @code{let}. The second part is a list, called a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3756 @dfn{varlist}, each element of which is either a symbol by itself or a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3757 two-element list, the first element of which is a symbol. The third
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3758 part of the @code{let} expression is the body of the @code{let}. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3759 body usually consists of one or more lists.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3760
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3761 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3762 A template for a @code{let} expression looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3763
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3764 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3765 (let @var{varlist} @var{body}@dots{})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3766 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3767
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3768 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3769 The symbols in the varlist are the variables that are given initial
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3770 values by the @code{let} special form. Symbols by themselves are given
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3771 the initial value of @code{nil}; and each symbol that is the first
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3772 element of a two-element list is bound to the value that is returned
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3773 when the Lisp interpreter evaluates the second element.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3774
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3775 Thus, a varlist might look like this: @code{(thread (needles 3))}. In
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3776 this case, in a @code{let} expression, Emacs binds the symbol
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3777 @code{thread} to an initial value of @code{nil}, and binds the symbol
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3778 @code{needles} to an initial value of 3.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3779
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3780 When you write a @code{let} expression, what you do is put the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3781 appropriate expressions in the slots of the @code{let} expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3782 template.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3783
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3784 If the varlist is composed of two-element lists, as is often the case,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3785 the template for the @code{let} expression looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3786
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3787 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3788 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3789 (let ((@var{variable} @var{value})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3790 (@var{variable} @var{value})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3791 @dots{})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3792 @var{body}@dots{})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3793 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3794 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3795
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3796 @node Sample let Expression, Uninitialized let Variables, Parts of let Expression, let
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3797 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3798 @subsection Sample @code{let} Expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3799 @cindex Sample @code{let} expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3800 @cindex @code{let} expression sample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3801
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3802 The following expression creates and gives initial values
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3803 to the two variables @code{zebra} and @code{tiger}. The body of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3804 @code{let} expression is a list which calls the @code{message} function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3805
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3806 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3807 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3808 (let ((zebra 'stripes)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3809 (tiger 'fierce))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3810 (message "One kind of animal has %s and another is %s."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3811 zebra tiger))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3812 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3813 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3814
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3815 Here, the varlist is @code{((zebra 'stripes) (tiger 'fierce))}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3816
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3817 The two variables are @code{zebra} and @code{tiger}. Each variable is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3818 the first element of a two-element list and each value is the second
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3819 element of its two-element list. In the varlist, Emacs binds the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3820 variable @code{zebra} to the value @code{stripes}@footnote{According
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3821 to Jared Diamond in @cite{Guns, Germs, and Steel}, ``@dots{} zebras
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3822 become impossibly dangerous as they grow older'' but the claim here is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3823 that they do not become fierce like a tiger. (1997, W. W. Norton and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3824 Co., ISBN 0-393-03894-2, page 171)}, and binds the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3825 variable @code{tiger} to the value @code{fierce}. In this example,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3826 both values are symbols preceded by a quote. The values could just as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3827 well have been another list or a string. The body of the @code{let}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3828 follows after the list holding the variables. In this example, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3829 body is a list that uses the @code{message} function to print a string
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3830 in the echo area.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3831
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3832 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3833 You may evaluate the example in the usual fashion, by placing the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3834 cursor after the last parenthesis and typing @kbd{C-x C-e}. When you do
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3835 this, the following will appear in the echo area:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3836
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3837 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3838 "One kind of animal has stripes and another is fierce."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3839 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3840
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3841 As we have seen before, the @code{message} function prints its first
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3842 argument, except for @samp{%s}. In this example, the value of the variable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3843 @code{zebra} is printed at the location of the first @samp{%s} and the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3844 value of the variable @code{tiger} is printed at the location of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3845 second @samp{%s}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3846
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3847 @node Uninitialized let Variables, , Sample let Expression, let
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3848 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3849 @subsection Uninitialized Variables in a @code{let} Statement
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3850 @cindex Uninitialized @code{let} variables
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3851 @cindex @code{let} variables uninitialized
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3852
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3853 If you do not bind the variables in a @code{let} statement to specific
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3854 initial values, they will automatically be bound to an initial value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3855 @code{nil}, as in the following expression:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3856
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3857 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3858 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3859 (let ((birch 3)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3860 pine
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3861 fir
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3862 (oak 'some))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3863 (message
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3864 "Here are %d variables with %s, %s, and %s value."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3865 birch pine fir oak))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3866 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3867 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3868
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3869 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3870 Here, the varlist is @code{((birch 3) pine fir (oak 'some))}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3871
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3872 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3873 If you evaluate this expression in the usual way, the following will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3874 appear in your echo area:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3875
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3876 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3877 "Here are 3 variables with nil, nil, and some value."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3878 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3879
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3880 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3881 In this example, Emacs binds the symbol @code{birch} to the number 3,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3882 binds the symbols @code{pine} and @code{fir} to @code{nil}, and binds
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3883 the symbol @code{oak} to the value @code{some}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3884
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3885 Note that in the first part of the @code{let}, the variables @code{pine}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3886 and @code{fir} stand alone as atoms that are not surrounded by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3887 parentheses; this is because they are being bound to @code{nil}, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3888 empty list. But @code{oak} is bound to @code{some} and so is a part of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3889 the list @code{(oak 'some)}. Similarly, @code{birch} is bound to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3890 number 3 and so is in a list with that number. (Since a number
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3891 evaluates to itself, the number does not need to be quoted. Also, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3892 number is printed in the message using a @samp{%d} rather than a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3893 @samp{%s}.) The four variables as a group are put into a list to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3894 delimit them from the body of the @code{let}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3895
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3896 @node if, else, let, Writing Defuns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3897 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3898 @section The @code{if} Special Form
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3899 @findex if
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3900 @cindex Conditional with @code{if}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3901
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3902 A third special form, in addition to @code{defun} and @code{let}, is the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3903 conditional @code{if}. This form is used to instruct the computer to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3904 make decisions. You can write function definitions without using
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3905 @code{if}, but it is used often enough, and is important enough, to be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3906 included here. It is used, for example, in the code for the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3907 function @code{beginning-of-buffer}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3908
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3909 The basic idea behind an @code{if}, is that ``@emph{if} a test is true,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3910 @emph{then} an expression is evaluated.'' If the test is not true, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3911 expression is not evaluated. For example, you might make a decision
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3912 such as, ``if it is warm and sunny, then go to the beach!''
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3913
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3914 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3915 * if in more detail::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3916 * type-of-animal in detail:: An example of an @code{if} expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3917 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3918
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3919 @node if in more detail, type-of-animal in detail, if, if
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3920 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3921 @unnumberedsubsec @code{if} in more detail
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3922 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3923
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3924 @cindex @samp{if-part} defined
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3925 @cindex @samp{then-part} defined
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3926 An @code{if} expression written in Lisp does not use the word `then';
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3927 the test and the action are the second and third elements of the list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3928 whose first element is @code{if}. Nonetheless, the test part of an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3929 @code{if} expression is often called the @dfn{if-part} and the second
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3930 argument is often called the @dfn{then-part}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3931
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3932 Also, when an @code{if} expression is written, the true-or-false-test
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3933 is usually written on the same line as the symbol @code{if}, but the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3934 action to carry out if the test is true, the ``then-part'', is written
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3935 on the second and subsequent lines. This makes the @code{if}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3936 expression easier to read.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3937
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3938 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3939 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3940 (if @var{true-or-false-test}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3941 @var{action-to-carry-out-if-test-is-true})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3942 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3943 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3944
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3945 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3946 The true-or-false-test will be an expression that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3947 is evaluated by the Lisp interpreter.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3948
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3949 Here is an example that you can evaluate in the usual manner. The test
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3950 is whether the number 5 is greater than the number 4. Since it is, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3951 message @samp{5 is greater than 4!} will be printed.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3952
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3953 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3954 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3955 (if (> 5 4) ; @r{if-part}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3956 (message "5 is greater than 4!")) ; @r{then-part}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3957 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3958 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3959
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3960 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3961 (The function @code{>} tests whether its first argument is greater than
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3962 its second argument and returns true if it is.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3963 @findex > (greater than)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3964
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3965 Of course, in actual use, the test in an @code{if} expression will not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3966 be fixed for all time as it is by the expression @code{(> 5 4)}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3967 Instead, at least one of the variables used in the test will be bound to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3968 a value that is not known ahead of time. (If the value were known ahead
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3969 of time, we would not need to run the test!)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3970
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3971 For example, the value may be bound to an argument of a function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3972 definition. In the following function definition, the character of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3973 animal is a value that is passed to the function. If the value bound to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3974 @code{characteristic} is @code{fierce}, then the message, @samp{It's a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3975 tiger!} will be printed; otherwise, @code{nil} will be returned.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3976
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3977 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3978 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3979 (defun type-of-animal (characteristic)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3980 "Print message in echo area depending on CHARACTERISTIC.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3981 If the CHARACTERISTIC is the symbol `fierce',
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3982 then warn of a tiger."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3983 (if (equal characteristic 'fierce)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3984 (message "It's a tiger!")))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3985 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3986 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3987
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3988 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3989 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3990 If you are reading this inside of GNU Emacs, you can evaluate the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3991 function definition in the usual way to install it in Emacs, and then you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3992 can evaluate the following two expressions to see the results:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3993
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3994 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3995 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3996 (type-of-animal 'fierce)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3997
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3998 (type-of-animal 'zebra)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3999
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4000 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4001 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4002
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4003 @c Following sentences rewritten to prevent overfull hbox.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4004 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4005 When you evaluate @code{(type-of-animal 'fierce)}, you will see the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4006 following message printed in the echo area: @code{"It's a tiger!"}; and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4007 when you evaluate @code{(type-of-animal 'zebra)} you will see @code{nil}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4008 printed in the echo area.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4009
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4010 @node type-of-animal in detail, , if in more detail, if
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4011 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4012 @subsection The @code{type-of-animal} Function in Detail
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4013
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4014 Let's look at the @code{type-of-animal} function in detail.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4015
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4016 The function definition for @code{type-of-animal} was written by filling
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4017 the slots of two templates, one for a function definition as a whole, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4018 a second for an @code{if} expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4019
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4020 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4021 The template for every function that is not interactive is:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4022
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4023 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4024 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4025 (defun @var{name-of-function} (@var{argument-list})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4026 "@var{documentation}@dots{}"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4027 @var{body}@dots{})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4028 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4029 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4030
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4031 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4032 The parts of the function that match this template look like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4033
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4034 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4035 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4036 (defun type-of-animal (characteristic)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4037 "Print message in echo area depending on CHARACTERISTIC.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4038 If the CHARACTERISTIC is the symbol `fierce',
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4039 then warn of a tiger."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4040 @var{body: the} @code{if} @var{expression})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4041 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4042 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4043
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4044 The name of function is @code{type-of-animal}; it is passed the value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4045 of one argument. The argument list is followed by a multi-line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4046 documentation string. The documentation string is included in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4047 example because it is a good habit to write documentation string for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4048 every function definition. The body of the function definition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4049 consists of the @code{if} expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4050
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4051 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4052 The template for an @code{if} expression looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4053
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4054 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4055 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4056 (if @var{true-or-false-test}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4057 @var{action-to-carry-out-if-the-test-returns-true})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4058 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4059 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4060
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4061 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4062 In the @code{type-of-animal} function, the code for the @code{if}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4063 looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4064
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4065 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4066 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4067 (if (equal characteristic 'fierce)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4068 (message "It's a tiger!")))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4069 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4070 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4071
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4072 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4073 Here, the true-or-false-test is the expression:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4074
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4075 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4076 (equal characteristic 'fierce)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4077 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4078
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4079 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4080 In Lisp, @code{equal} is a function that determines whether its first
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4081 argument is equal to its second argument. The second argument is the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4082 quoted symbol @code{'fierce} and the first argument is the value of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4083 symbol @code{characteristic}---in other words, the argument passed to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4084 this function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4085
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4086 In the first exercise of @code{type-of-animal}, the argument
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4087 @code{fierce} is passed to @code{type-of-animal}. Since @code{fierce}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4088 is equal to @code{fierce}, the expression, @code{(equal characteristic
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4089 'fierce)}, returns a value of true. When this happens, the @code{if}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4090 evaluates the second argument or then-part of the @code{if}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4091 @code{(message "It's tiger!")}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4092
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4093 On the other hand, in the second exercise of @code{type-of-animal}, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4094 argument @code{zebra} is passed to @code{type-of-animal}. @code{zebra}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4095 is not equal to @code{fierce}, so the then-part is not evaluated and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4096 @code{nil} is returned by the @code{if} expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4097
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4098 @node else, Truth & Falsehood, if, Writing Defuns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4099 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4100 @section If--then--else Expressions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4101 @cindex Else
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4102
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4103 An @code{if} expression may have an optional third argument, called
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4104 the @dfn{else-part}, for the case when the true-or-false-test returns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4105 false. When this happens, the second argument or then-part of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4106 overall @code{if} expression is @emph{not} evaluated, but the third or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4107 else-part @emph{is} evaluated. You might think of this as the cloudy
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4108 day alternative for the decision ``if it is warm and sunny, then go to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4109 the beach, else read a book!''.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4110
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4111 The word ``else'' is not written in the Lisp code; the else-part of an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4112 @code{if} expression comes after the then-part. In the written Lisp, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4113 else-part is usually written to start on a line of its own and is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4114 indented less than the then-part:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4115
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4116 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4117 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4118 (if @var{true-or-false-test}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4119 @var{action-to-carry-out-if-the-test-returns-true}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4120 @var{action-to-carry-out-if-the-test-returns-false})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4121 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4122 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4123
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4124 For example, the following @code{if} expression prints the message @samp{4
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4125 is not greater than 5!} when you evaluate it in the usual way:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4126
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4127 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4128 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4129 (if (> 4 5) ; @r{if-part}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4130 (message "4 falsely greater than 5!") ; @r{then-part}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4131 (message "4 is not greater than 5!")) ; @r{else-part}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4132 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4133 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4134
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4135 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4136 Note that the different levels of indentation make it easy to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4137 distinguish the then-part from the else-part. (GNU Emacs has several
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4138 commands that automatically indent @code{if} expressions correctly.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4139 @xref{Typing Lists, , GNU Emacs Helps You Type Lists}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4140
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4141 We can extend the @code{type-of-animal} function to include an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4142 else-part by simply incorporating an additional part to the @code{if}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4143 expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4144
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4145 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4146 You can see the consequences of doing this if you evaluate the following
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4147 version of the @code{type-of-animal} function definition to install it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4148 and then evaluate the two subsequent expressions to pass different
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4149 arguments to the function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4150
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4151 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4152 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4153 (defun type-of-animal (characteristic) ; @r{Second version.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4154 "Print message in echo area depending on CHARACTERISTIC.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4155 If the CHARACTERISTIC is the symbol `fierce',
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4156 then warn of a tiger;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4157 else say it's not fierce."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4158 (if (equal characteristic 'fierce)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4159 (message "It's a tiger!")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4160 (message "It's not fierce!")))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4161 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4162 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4163 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4164
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4165 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4166 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4167 (type-of-animal 'fierce)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4168
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4169 (type-of-animal 'zebra)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4170
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4171 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4172 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4173
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4174 @c Following sentence rewritten to prevent overfull hbox.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4175 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4176 When you evaluate @code{(type-of-animal 'fierce)}, you will see the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4177 following message printed in the echo area: @code{"It's a tiger!"}; but
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4178 when you evaluate @code{(type-of-animal 'zebra)}, you will see
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4179 @code{"It's not fierce!"}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4180
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4181 (Of course, if the @var{characteristic} were @code{ferocious}, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4182 message @code{"It's not fierce!"} would be printed; and it would be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4183 misleading! When you write code, you need to take into account the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4184 possibility that some such argument will be tested by the @code{if}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4185 and write your program accordingly.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4186
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4187 @node Truth & Falsehood, save-excursion, else, Writing Defuns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4188 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4189 @section Truth and Falsehood in Emacs Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4190 @cindex Truth and falsehood in Emacs Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4191 @cindex Falsehood and truth in Emacs Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4192 @findex nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4193
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4194 There is an important aspect to the truth test in an @code{if}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4195 expression. So far, we have spoken of `true' and `false' as values of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4196 predicates as if they were new kinds of Emacs Lisp objects. In fact,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4197 `false' is just our old friend @code{nil}. Anything else---anything
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4198 at all---is `true'.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4199
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4200 The expression that tests for truth is interpreted as @dfn{true}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4201 if the result of evaluating it is a value that is not @code{nil}. In
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4202 other words, the result of the test is considered true if the value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4203 returned is a number such as 47, a string such as @code{"hello"}, or a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4204 symbol (other than @code{nil}) such as @code{flowers}, or a list (so
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4205 long as it is not empty), or even a buffer!
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4206
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4207 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4208 * nil explained:: @code{nil} has two meanings.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4209 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4210
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4211 @node nil explained, , Truth & Falsehood, Truth & Falsehood
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4212 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4213 @unnumberedsubsec An explanation of @code{nil}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4214 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4215
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4216 Before illustrating a test for truth, we need an explanation of @code{nil}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4217
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4218 In Emacs Lisp, the symbol @code{nil} has two meanings. First, it means the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4219 empty list. Second, it means false and is the value returned when a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4220 true-or-false-test tests false. @code{nil} can be written as an empty
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4221 list, @code{()}, or as @code{nil}. As far as the Lisp interpreter is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4222 concerned, @code{()} and @code{nil} are the same. Humans, however, tend
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4223 to use @code{nil} for false and @code{()} for the empty list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4224
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4225 In Emacs Lisp, any value that is not @code{nil}---is not the empty
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4226 list---is considered true. This means that if an evaluation returns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4227 something that is not an empty list, an @code{if} expression will test
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4228 true. For example, if a number is put in the slot for the test, it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4229 will be evaluated and will return itself, since that is what numbers
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4230 do when evaluated. In this conditional, the @code{if} expression will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4231 test true. The expression tests false only when @code{nil}, an empty
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4232 list, is returned by evaluating the expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4233
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4234 You can see this by evaluating the two expressions in the following examples.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4235
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4236 In the first example, the number 4 is evaluated as the test in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4237 @code{if} expression and returns itself; consequently, the then-part
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4238 of the expression is evaluated and returned: @samp{true} appears in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4239 the echo area. In the second example, the @code{nil} indicates false;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4240 consequently, the else-part of the expression is evaluated and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4241 returned: @samp{false} appears in the echo area.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4242
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4243 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4244 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4245 (if 4
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4246 'true
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4247 'false)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4248 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4249
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4250 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4251 (if nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4252 'true
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4253 'false)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4254 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4255 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4256
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4257 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4258 Incidentally, if some other useful value is not available for a test that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4259 returns true, then the Lisp interpreter will return the symbol @code{t}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4260 for true. For example, the expression @code{(> 5 4)} returns @code{t}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4261 when evaluated, as you can see by evaluating it in the usual way:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4262
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4263 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4264 (> 5 4)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4265 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4266
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4267 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4268 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4269 On the other hand, this function returns @code{nil} if the test is false.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4270
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4271 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4272 (> 4 5)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4273 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4274
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4275 @node save-excursion, Review, Truth & Falsehood, Writing Defuns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4276 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4277 @section @code{save-excursion}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4278 @findex save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4279 @cindex Region, what it is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4280 @cindex Preserving point, mark, and buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4281 @cindex Point, mark, buffer preservation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4282 @findex point
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4283 @findex mark
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4284
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4285 The @code{save-excursion} function is the fourth and final special form
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4286 that we will discuss in this chapter.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4287
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4288 In Emacs Lisp programs used for editing, the @code{save-excursion}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4289 function is very common. It saves the location of point and mark,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4290 executes the body of the function, and then restores point and mark to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4291 their previous positions if their locations were changed. Its primary
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4292 purpose is to keep the user from being surprised and disturbed by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4293 unexpected movement of point or mark.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4294
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4295 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4296 * Point and mark:: A review of various locations.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4297 * Template for save-excursion::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4298 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4299
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4300 @node Point and mark, Template for save-excursion, save-excursion, save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4301 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4302 @unnumberedsubsec Point and Mark
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4303 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4304
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4305 Before discussing @code{save-excursion}, however, it may be useful
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4306 first to review what point and mark are in GNU Emacs. @dfn{Point} is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4307 the current location of the cursor. Wherever the cursor
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4308 is, that is point. More precisely, on terminals where the cursor
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4309 appears to be on top of a character, point is immediately before the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4310 character. In Emacs Lisp, point is an integer. The first character in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4311 a buffer is number one, the second is number two, and so on. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4312 function @code{point} returns the current position of the cursor as a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4313 number. Each buffer has its own value for point.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4314
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4315 The @dfn{mark} is another position in the buffer; its value can be set
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4316 with a command such as @kbd{C-@key{SPC}} (@code{set-mark-command}). If
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4317 a mark has been set, you can use the command @kbd{C-x C-x}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4318 (@code{exchange-point-and-mark}) to cause the cursor to jump to the mark
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4319 and set the mark to be the previous position of point. In addition, if
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4320 you set another mark, the position of the previous mark is saved in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4321 mark ring. Many mark positions can be saved this way. You can jump the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4322 cursor to a saved mark by typing @kbd{C-u C-@key{SPC}} one or more
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4323 times.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4324
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4325 The part of the buffer between point and mark is called @dfn{the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4326 region}. Numerous commands work on the region, including
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4327 @code{center-region}, @code{count-lines-region}, @code{kill-region}, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4328 @code{print-region}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4329
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4330 The @code{save-excursion} special form saves the locations of point and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4331 mark and restores those positions after the code within the body of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4332 special form is evaluated by the Lisp interpreter. Thus, if point were
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4333 in the beginning of a piece of text and some code moved point to the end
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4334 of the buffer, the @code{save-excursion} would put point back to where
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4335 it was before, after the expressions in the body of the function were
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4336 evaluated.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4337
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4338 In Emacs, a function frequently moves point as part of its internal
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4339 workings even though a user would not expect this. For example,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4340 @code{count-lines-region} moves point. To prevent the user from being
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4341 bothered by jumps that are both unexpected and (from the user's point of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4342 view) unnecessary, @code{save-excursion} is often used to keep point and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4343 mark in the location expected by the user. The use of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4344 @code{save-excursion} is good housekeeping.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4345
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4346 To make sure the house stays clean, @code{save-excursion} restores the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4347 values of point and mark even if something goes wrong in the code inside
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4348 of it (or, to be more precise and to use the proper jargon, ``in case of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4349 abnormal exit''). This feature is very helpful.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4350
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4351 In addition to recording the values of point and mark,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4352 @code{save-excursion} keeps track of the current buffer, and restores
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4353 it, too. This means you can write code that will change the buffer and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4354 have @code{save-excursion} switch you back to the original buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4355 This is how @code{save-excursion} is used in @code{append-to-buffer}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4356 (@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4357
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4358 @node Template for save-excursion, , Point and mark, save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4359 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4360 @subsection Template for a @code{save-excursion} Expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4361
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4362 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4363 The template for code using @code{save-excursion} is simple:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4364
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4365 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4366 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4367 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4368 @var{body}@dots{})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4369 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4370 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4371
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4372 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4373 The body of the function is one or more expressions that will be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4374 evaluated in sequence by the Lisp interpreter. If there is more than
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4375 one expression in the body, the value of the last one will be returned
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4376 as the value of the @code{save-excursion} function. The other
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4377 expressions in the body are evaluated only for their side effects; and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4378 @code{save-excursion} itself is used only for its side effect (which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4379 is restoring the positions of point and mark).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4380
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4381 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4382 In more detail, the template for a @code{save-excursion} expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4383 looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4384
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4385 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4386 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4387 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4388 @var{first-expression-in-body}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4389 @var{second-expression-in-body}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4390 @var{third-expression-in-body}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4391 @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4392 @var{last-expression-in-body})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4393 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4394 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4395
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4396 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4397 An expression, of course, may be a symbol on its own or a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4398
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4399 In Emacs Lisp code, a @code{save-excursion} expression often occurs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4400 within the body of a @code{let} expression. It looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4401
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4402 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4403 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4404 (let @var{varlist}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4405 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4406 @var{body}@dots{}))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4407 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4408 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4409
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4410 @node Review, defun Exercises, save-excursion, Writing Defuns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4411 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4412 @section Review
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4413
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4414 In the last few chapters we have introduced a fair number of functions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4415 and special forms. Here they are described in brief, along with a few
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4416 similar functions that have not been mentioned yet.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4417
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4418 @table @code
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4419 @item eval-last-sexp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4420 Evaluate the last symbolic expression before the current location of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4421 point. The value is printed in the echo area unless the function is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4422 invoked with an argument; in that case, the output is printed in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4423 current buffer. This command is normally bound to @kbd{C-x C-e}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4424
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4425 @item defun
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4426 Define function. This special form has up to five parts: the name,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4427 a template for the arguments that will be passed to the function,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4428 documentation, an optional interactive declaration, and the body of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4429 definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4430
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4431 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4432 For example, in an early version of Emacs, the function definition was
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4433 as follows. (It is slightly more complex now that it seeks the first
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4434 non-whitespace character rather than the first visible character.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4435
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4436 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4437 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4438 (defun back-to-indentation ()
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4439 "Move point to first visible character on line."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4440 (interactive)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4441 (beginning-of-line 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4442 (skip-chars-forward " \t"))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4443 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4444 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4445
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4446 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4447 In GNU Emacs 22,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4448
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4449 (defun backward-to-indentation (&optional arg)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4450 "Move backward ARG lines and position at first nonblank character."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4451 (interactive "p")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4452 (forward-line (- (or arg 1)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4453 (skip-chars-forward " \t"))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4454
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4455 (defun back-to-indentation ()
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4456 "Move point to the first non-whitespace character on this line."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4457 (interactive)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4458 (beginning-of-line 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4459 (skip-syntax-forward " " (line-end-position))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4460 ;; Move back over chars that have whitespace syntax but have the p flag.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4461 (backward-prefix-chars))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4462 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4463
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4464 @item interactive
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4465 Declare to the interpreter that the function can be used
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4466 interactively. This special form may be followed by a string with one
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4467 or more parts that pass the information to the arguments of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4468 function, in sequence. These parts may also tell the interpreter to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4469 prompt for information. Parts of the string are separated by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4470 newlines, @samp{\n}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4471
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4472 @need 1000
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4473 Common code characters are:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4474
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4475 @table @code
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4476 @item b
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4477 The name of an existing buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4478
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4479 @item f
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4480 The name of an existing file.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4481
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4482 @item p
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4483 The numeric prefix argument. (Note that this `p' is lower case.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4484
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4485 @item r
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4486 Point and the mark, as two numeric arguments, smallest first. This
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4487 is the only code letter that specifies two successive arguments
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4488 rather than one.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4489 @end table
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4490
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4491 @xref{Interactive Codes, , Code Characters for @samp{interactive},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4492 elisp, The GNU Emacs Lisp Reference Manual}, for a complete list of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4493 code characters.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4494
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4495 @item let
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4496 Declare that a list of variables is for use within the body of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4497 @code{let} and give them an initial value, either @code{nil} or a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4498 specified value; then evaluate the rest of the expressions in the body
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4499 of the @code{let} and return the value of the last one. Inside the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4500 body of the @code{let}, the Lisp interpreter does not see the values of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4501 the variables of the same names that are bound outside of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4502 @code{let}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4503
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4504 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4505 For example,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4506
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4507 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4508 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4509 (let ((foo (buffer-name))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4510 (bar (buffer-size)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4511 (message
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4512 "This buffer is %s and has %d characters."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4513 foo bar))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4514 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4515 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4516
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4517 @item save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4518 Record the values of point and mark and the current buffer before
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4519 evaluating the body of this special form. Restore the values of point
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4520 and mark and buffer afterward.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4521
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4522 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4523 For example,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4524
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4525 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4526 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4527 (message "We are %d characters into this buffer."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4528 (- (point)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4529 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4530 (goto-char (point-min)) (point))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4531 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4532 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4533
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4534 @item if
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4535 Evaluate the first argument to the function; if it is true, evaluate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4536 the second argument; else evaluate the third argument, if there is one.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4537
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4538 The @code{if} special form is called a @dfn{conditional}. There are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4539 other conditionals in Emacs Lisp, but @code{if} is perhaps the most
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4540 commonly used.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4541
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4542 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4543 For example,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4544
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4545 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4546 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4547 (if (= 22 emacs-major-version)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4548 (message "This is version 22 Emacs")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4549 (message "This is not version 22 Emacs"))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4550 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4551 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4552
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4553 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4554 @item <
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4555 @itemx >
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4556 @itemx <=
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4557 @itemx >=
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4558 The @code{<} function tests whether its first argument is smaller than
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4559 its second argument. A corresponding function, @code{>}, tests whether
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4560 the first argument is greater than the second. Likewise, @code{<=}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4561 tests whether the first argument is less than or equal to the second and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4562 @code{>=} tests whether the first argument is greater than or equal to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4563 the second. In all cases, both arguments must be numbers or markers
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4564 (markers indicate positions in buffers).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4565
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4566 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4567 @item =
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4568 The @code{=} function tests whether two arguments, both numbers or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4569 markers, are equal.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4570
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4571 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4572 @item equal
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4573 @itemx eq
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4574 Test whether two objects are the same. @code{equal} uses one meaning
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4575 of the word `same' and @code{eq} uses another: @code{equal} returns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4576 true if the two objects have a similar structure and contents, such as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4577 two copies of the same book. On the other hand, @code{eq}, returns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4578 true if both arguments are actually the same object.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4579 @findex equal
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4580 @findex eq
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4581
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4582 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4583 @item string<
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4584 @itemx string-lessp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4585 @itemx string=
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4586 @itemx string-equal
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4587 The @code{string-lessp} function tests whether its first argument is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4588 smaller than the second argument. A shorter, alternative name for the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4589 same function (a @code{defalias}) is @code{string<}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4590
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4591 The arguments to @code{string-lessp} must be strings or symbols; the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4592 ordering is lexicographic, so case is significant. The print names of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4593 symbols are used instead of the symbols themselves.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4594
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4595 @cindex @samp{empty string} defined
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4596 An empty string, @samp{""}, a string with no characters in it, is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4597 smaller than any string of characters.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4598
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4599 @code{string-equal} provides the corresponding test for equality. Its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4600 shorter, alternative name is @code{string=}. There are no string test
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4601 functions that correspond to @var{>}, @code{>=}, or @code{<=}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4602
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4603 @item message
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4604 Print a message in the echo area. The first argument is a string that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4605 can contain @samp{%s}, @samp{%d}, or @samp{%c} to print the value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4606 arguments that follow the string. The argument used by @samp{%s} must
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4607 be a string or a symbol; the argument used by @samp{%d} must be a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4608 number. The argument used by @samp{%c} must be an @sc{ascii} code
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4609 number; it will be printed as the character with that @sc{ascii} code.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4610 (Various other %-sequences have not been mentioned.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4611
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4612 @item setq
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4613 @itemx set
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4614 The @code{setq} function sets the value of its first argument to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4615 value of the second argument. The first argument is automatically
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4616 quoted by @code{setq}. It does the same for succeeding pairs of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4617 arguments. Another function, @code{set}, takes only two arguments and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4618 evaluates both of them before setting the value returned by its first
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4619 argument to the value returned by its second argument.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4620
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4621 @item buffer-name
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4622 Without an argument, return the name of the buffer, as a string.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4623
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4624 @itemx buffer-file-name
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4625 Without an argument, return the name of the file the buffer is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4626 visiting.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4627
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4628 @item current-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4629 Return the buffer in which Emacs is active; it may not be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4630 the buffer that is visible on the screen.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4631
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4632 @item other-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4633 Return the most recently selected buffer (other than the buffer passed
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4634 to @code{other-buffer} as an argument and other than the current
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4635 buffer).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4636
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4637 @item switch-to-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4638 Select a buffer for Emacs to be active in and display it in the current
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4639 window so users can look at it. Usually bound to @kbd{C-x b}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4640
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4641 @item set-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4642 Switch Emacs' attention to a buffer on which programs will run. Don't
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4643 alter what the window is showing.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4644
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4645 @item buffer-size
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4646 Return the number of characters in the current buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4647
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4648 @item point
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4649 Return the value of the current position of the cursor, as an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4650 integer counting the number of characters from the beginning of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4651 buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4652
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4653 @item point-min
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4654 Return the minimum permissible value of point in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4655 the current buffer. This is 1, unless narrowing is in effect.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4656
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4657 @item point-max
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4658 Return the value of the maximum permissible value of point in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4659 current buffer. This is the end of the buffer, unless narrowing is in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4660 effect.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4661 @end table
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4662
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4663 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4664 @node defun Exercises, , Review, Writing Defuns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4665 @section Exercises
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4666
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4667 @itemize @bullet
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4668 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4669 Write a non-interactive function that doubles the value of its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4670 argument, a number. Make that function interactive.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4671
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4672 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4673 Write a function that tests whether the current value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4674 @code{fill-column} is greater than the argument passed to the function,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4675 and if so, prints an appropriate message.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4676 @end itemize
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4677
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4678 @node Buffer Walk Through, More Complex, Writing Defuns, Top
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4679 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4680 @chapter A Few Buffer--Related Functions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4681
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4682 In this chapter we study in detail several of the functions used in GNU
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4683 Emacs. This is called a ``walk-through''. These functions are used as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4684 examples of Lisp code, but are not imaginary examples; with the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4685 exception of the first, simplified function definition, these functions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4686 show the actual code used in GNU Emacs. You can learn a great deal from
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4687 these definitions. The functions described here are all related to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4688 buffers. Later, we will study other functions.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4689
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4690 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4691 * Finding More:: How to find more information.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4692 * simplified-beginning-of-buffer:: Shows @code{goto-char},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4693 @code{point-min}, and @code{push-mark}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4694 * mark-whole-buffer:: Almost the same as @code{beginning-of-buffer}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4695 * append-to-buffer:: Uses @code{save-excursion} and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4696 @code{insert-buffer-substring}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4697 * Buffer Related Review:: Review.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4698 * Buffer Exercises::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4699 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4700
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4701 @node Finding More, simplified-beginning-of-buffer, Buffer Walk Through, Buffer Walk Through
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4702 @section Finding More Information
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4703
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4704 @findex describe-function, @r{introduced}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4705 @cindex Find function documentation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4706 In this walk-through, I will describe each new function as we come to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4707 it, sometimes in detail and sometimes briefly. If you are interested,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4708 you can get the full documentation of any Emacs Lisp function at any
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4709 time by typing @kbd{C-h f} and then the name of the function (and then
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4710 @key{RET}). Similarly, you can get the full documentation for a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4711 variable by typing @kbd{C-h v} and then the name of the variable (and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4712 then @key{RET}).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4713
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4714 @cindex Find source of function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4715 @c In version 22, tells location both of C and of Emacs Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4716 Also, @code{describe-function} will tell you the location of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4717 function definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4718
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4719 Put point into the name of the file that contains the function and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4720 press the @key{RET} key. In this case, @key{RET} means
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4721 @code{push-button} rather than `return' or `enter'. Emacs will take
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4722 you directly to the function definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4723
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4724 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4725 Not In version 22
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4726
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4727 If you move point over the file name and press
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4728 the @key{RET} key, which in this case means @code{help-follow} rather
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4729 than `return' or `enter', Emacs will take you directly to the function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4730 definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4731 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4732
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4733 More generally, if you want to see a function in its original source
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4734 file, you can use the @code{find-tags} function to jump to it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4735 @code{find-tags} works with a wide variety of languages, not just
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4736 Lisp, and C, and it works with non-programming text as well. For
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4737 example, @code{find-tags} will jump to the various nodes in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4738 Texinfo source file of this document.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4739 The @code{find-tags} function depends on `tags tables' that record
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4740 the locations of the functions, variables, and other items to which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4741 @code{find-tags} jumps.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4742
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4743 To use the @code{find-tags} command, type @kbd{M-.} (i.e., press the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4744 period key while holding down the @key{META} key, or else type the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4745 @key{ESC} key and then type the period key), and then, at the prompt,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4746 type in the name of the function whose source code you want to see,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4747 such as @code{mark-whole-buffer}, and then type @key{RET}. Emacs will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4748 switch buffers and display the source code for the function on your
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4749 screen. To switch back to your current buffer, type @kbd{C-x b
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4750 @key{RET}}. (On some keyboards, the @key{META} key is labelled
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4751 @key{ALT}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4752
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4753 @c !!! 22.1.1 tags table location in this paragraph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4754 @cindex TAGS table, specifying
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4755 @findex find-tags
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4756 Depending on how the initial default values of your copy of Emacs are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4757 set, you may also need to specify the location of your `tags table',
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4758 which is a file called @file{TAGS}. For example, if you are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4759 interested in Emacs sources, the tags table you will most likely want,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4760 if it has already been created for you, will be in a subdirectory of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4761 the @file{/usr/local/share/emacs/} directory; thus you would use the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4762 @code{M-x visit-tags-table} command and specify a pathname such as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4763 @file{/usr/local/share/emacs/22.1.1/lisp/TAGS}. If the tags table
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4764 has not already been created, you will have to create it yourself. It
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4765 will in a file such as @file{/usr/local/src/emacs/src/TAGS}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4766
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4767 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4768 To create a @file{TAGS} file in a specific directory, switch to that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4769 directory in Emacs using @kbd{M-x cd} command, or list the directory
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4770 with @kbd{C-x d} (@code{dired}). Then run the compile command, with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4771 @w{@code{etags *.el}} as the command to execute:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4772
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4773 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4774 M-x compile RET etags *.el RET
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4775 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4776
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4777 For more information, see @ref{etags, , Create Your Own @file{TAGS} File}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4778
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4779 After you become more familiar with Emacs Lisp, you will find that you will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4780 frequently use @code{find-tags} to navigate your way around source code;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4781 and you will create your own @file{TAGS} tables.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4782
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4783 @cindex Library, as term for `file'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4784 Incidentally, the files that contain Lisp code are conventionally
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4785 called @dfn{libraries}. The metaphor is derived from that of a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4786 specialized library, such as a law library or an engineering library,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4787 rather than a general library. Each library, or file, contains
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4788 functions that relate to a particular topic or activity, such as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4789 @file{abbrev.el} for handling abbreviations and other typing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4790 shortcuts, and @file{help.el} for on-line help. (Sometimes several
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4791 libraries provide code for a single activity, as the various
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4792 @file{rmail@dots{}} files provide code for reading electronic mail.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4793 In @cite{The GNU Emacs Manual}, you will see sentences such as ``The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4794 @kbd{C-h p} command lets you search the standard Emacs Lisp libraries
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4795 by topic keywords.''
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4796
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4797 @node simplified-beginning-of-buffer, mark-whole-buffer, Finding More, Buffer Walk Through
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4798 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4799 @section A Simplified @code{beginning-of-buffer} Definition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4800 @findex simplified-beginning-of-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4801
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4802 The @code{beginning-of-buffer} command is a good function to start with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4803 since you are likely to be familiar with it and it is easy to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4804 understand. Used as an interactive command, @code{beginning-of-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4805 moves the cursor to the beginning of the buffer, leaving the mark at the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4806 previous position. It is generally bound to @kbd{M-<}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4807
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4808 In this section, we will discuss a shortened version of the function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4809 that shows how it is most frequently used. This shortened function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4810 works as written, but it does not contain the code for a complex option.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4811 In another section, we will describe the entire function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4812 (@xref{beginning-of-buffer, , Complete Definition of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4813 @code{beginning-of-buffer}}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4814
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4815 Before looking at the code, let's consider what the function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4816 definition has to contain: it must include an expression that makes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4817 the function interactive so it can be called by typing @kbd{M-x
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4818 beginning-of-buffer} or by typing a keychord such as @kbd{M-<}; it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4819 must include code to leave a mark at the original position in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4820 buffer; and it must include code to move the cursor to the beginning
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4821 of the buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4822
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4823 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4824 Here is the complete text of the shortened version of the function:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4825
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4826 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4827 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4828 (defun simplified-beginning-of-buffer ()
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4829 "Move point to the beginning of the buffer;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4830 leave mark at previous position."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4831 (interactive)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4832 (push-mark)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4833 (goto-char (point-min)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4834 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4835 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4836
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4837 Like all function definitions, this definition has five parts following
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4838 the special form @code{defun}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4839
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4840 @enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4841 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4842 The name: in this example, @code{simplified-beginning-of-buffer}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4843
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4844 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4845 A list of the arguments: in this example, an empty list, @code{()},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4846
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4847 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4848 The documentation string.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4849
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4850 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4851 The interactive expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4852
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4853 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4854 The body.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4855 @end enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4856
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4857 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4858 In this function definition, the argument list is empty; this means that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4859 this function does not require any arguments. (When we look at the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4860 definition for the complete function, we will see that it may be passed
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4861 an optional argument.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4862
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4863 The interactive expression tells Emacs that the function is intended to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4864 be used interactively. In this example, @code{interactive} does not have
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4865 an argument because @code{simplified-beginning-of-buffer} does not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4866 require one.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4867
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4868 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4869 The body of the function consists of the two lines:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4870
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4871 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4872 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4873 (push-mark)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4874 (goto-char (point-min))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4875 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4876 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4877
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4878 The first of these lines is the expression, @code{(push-mark)}. When
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4879 this expression is evaluated by the Lisp interpreter, it sets a mark at
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4880 the current position of the cursor, wherever that may be. The position
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4881 of this mark is saved in the mark ring.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4882
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4883 The next line is @code{(goto-char (point-min))}. This expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4884 jumps the cursor to the minimum point in the buffer, that is, to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4885 beginning of the buffer (or to the beginning of the accessible portion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4886 of the buffer if it is narrowed. @xref{Narrowing & Widening, ,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4887 Narrowing and Widening}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4888
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4889 The @code{push-mark} command sets a mark at the place where the cursor
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4890 was located before it was moved to the beginning of the buffer by the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4891 @code{(goto-char (point-min))} expression. Consequently, you can, if
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4892 you wish, go back to where you were originally by typing @kbd{C-x C-x}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4893
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4894 That is all there is to the function definition!
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4895
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4896 @findex describe-function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4897 When you are reading code such as this and come upon an unfamiliar
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4898 function, such as @code{goto-char}, you can find out what it does by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4899 using the @code{describe-function} command. To use this command, type
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4900 @kbd{C-h f} and then type in the name of the function and press
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4901 @key{RET}. The @code{describe-function} command will print the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4902 function's documentation string in a @file{*Help*} window. For
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4903 example, the documentation for @code{goto-char} is:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4904
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4905 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4906 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4907 Set point to POSITION, a number or marker.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4908 Beginning of buffer is position (point-min), end is (point-max).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4909 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4910 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4911
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4912 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4913 The function's one argument is the desired position.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4914
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4915 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4916 (The prompt for @code{describe-function} will offer you the symbol
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4917 under or preceding the cursor, so you can save typing by positioning
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4918 the cursor right over or after the function and then typing @kbd{C-h f
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4919 @key{RET}}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4920
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4921 The @code{end-of-buffer} function definition is written in the same way as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4922 the @code{beginning-of-buffer} definition except that the body of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4923 function contains the expression @code{(goto-char (point-max))} in place
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4924 of @code{(goto-char (point-min))}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4925
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4926 @node mark-whole-buffer, append-to-buffer, simplified-beginning-of-buffer, Buffer Walk Through
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4927 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4928 @section The Definition of @code{mark-whole-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4929 @findex mark-whole-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4930
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4931 The @code{mark-whole-buffer} function is no harder to understand than the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4932 @code{simplified-beginning-of-buffer} function. In this case, however,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4933 we will look at the complete function, not a shortened version.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4934
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4935 The @code{mark-whole-buffer} function is not as commonly used as the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4936 @code{beginning-of-buffer} function, but is useful nonetheless: it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4937 marks a whole buffer as a region by putting point at the beginning and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4938 a mark at the end of the buffer. It is generally bound to @kbd{C-x
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4939 h}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4940
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4941 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4942 * mark-whole-buffer overview::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4943 * Body of mark-whole-buffer:: Only three lines of code.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4944 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4945
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4946 @node mark-whole-buffer overview, Body of mark-whole-buffer, mark-whole-buffer, mark-whole-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4947 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4948 @unnumberedsubsec An overview of @code{mark-whole-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4949 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4950
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4951 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4952 In GNU Emacs 22, the code for the complete function looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4953
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4954 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4955 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4956 (defun mark-whole-buffer ()
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4957 "Put point at beginning and mark at end of buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4958 You probably should not use this function in Lisp programs;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4959 it is usually a mistake for a Lisp function to use any subroutine
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4960 that uses or sets the mark."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4961 (interactive)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4962 (push-mark (point))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4963 (push-mark (point-max) nil t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4964 (goto-char (point-min)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4965 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4966 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4967
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4968 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4969 Like all other functions, the @code{mark-whole-buffer} function fits
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4970 into the template for a function definition. The template looks like
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4971 this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4972
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4973 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4974 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4975 (defun @var{name-of-function} (@var{argument-list})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4976 "@var{documentation}@dots{}"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4977 (@var{interactive-expression}@dots{})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4978 @var{body}@dots{})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4979 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4980 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4981
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4982 Here is how the function works: the name of the function is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4983 @code{mark-whole-buffer}; it is followed by an empty argument list,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4984 @samp{()}, which means that the function does not require arguments.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4985 The documentation comes next.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4986
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4987 The next line is an @code{(interactive)} expression that tells Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4988 that the function will be used interactively. These details are similar
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4989 to the @code{simplified-beginning-of-buffer} function described in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4990 previous section.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4991
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4992 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4993 @node Body of mark-whole-buffer, , mark-whole-buffer overview, mark-whole-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4994 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4995 @subsection Body of @code{mark-whole-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4996
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4997 The body of the @code{mark-whole-buffer} function consists of three
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4998 lines of code:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
4999
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5000 @c GNU Emacs 22
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5001 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5002 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5003 (push-mark (point))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5004 (push-mark (point-max) nil t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5005 (goto-char (point-min))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5006 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5007 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5008
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5009 The first of these lines is the expression, @code{(push-mark (point))}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5010
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5011 This line does exactly the same job as the first line of the body of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5012 the @code{simplified-beginning-of-buffer} function, which is written
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5013 @code{(push-mark)}. In both cases, the Lisp interpreter sets a mark
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5014 at the current position of the cursor.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5015
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5016 I don't know why the expression in @code{mark-whole-buffer} is written
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5017 @code{(push-mark (point))} and the expression in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5018 @code{beginning-of-buffer} is written @code{(push-mark)}. Perhaps
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5019 whoever wrote the code did not know that the arguments for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5020 @code{push-mark} are optional and that if @code{push-mark} is not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5021 passed an argument, the function automatically sets mark at the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5022 location of point by default. Or perhaps the expression was written
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5023 so as to parallel the structure of the next line. In any case, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5024 line causes Emacs to determine the position of point and set a mark
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5025 there.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5026
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5027 In earlier versions of GNU Emacs, the next line of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5028 @code{mark-whole-buffer} was @code{(push-mark (point-max))}. This
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5029 expression sets a mark at the point in the buffer that has the highest
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5030 number. This will be the end of the buffer (or, if the buffer is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5031 narrowed, the end of the accessible portion of the buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5032 @xref{Narrowing & Widening, , Narrowing and Widening}, for more about
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5033 narrowing.) After this mark has been set, the previous mark, the one
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5034 set at point, is no longer set, but Emacs remembers its position, just
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5035 as all other recent marks are always remembered. This means that you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5036 can, if you wish, go back to that position by typing @kbd{C-u
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5037 C-@key{SPC}} twice.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5038
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5039 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5040 In GNU Emacs 22, the @code{(point-max)} is slightly more complicated.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5041 The line reads
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5042
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5043 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5044 (push-mark (point-max) nil t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5045 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5046
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5047 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5048 The expression works nearly the same as before. It sets a mark at the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5049 highest numbered place in the buffer that it can. However, in this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5050 version, @code{push-mark} has two additional arguments. The second
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5051 argument to @code{push-mark} is @code{nil}. This tells the function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5052 it @emph{should} display a message that says `Mark set' when it pushes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5053 the mark. The third argument is @code{t}. This tells
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5054 @code{push-mark} to activate the mark when Transient Mark mode is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5055 turned on. Transient Mark mode highlights the currently active
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5056 region. It is often turned off.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5057
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5058 Finally, the last line of the function is @code{(goto-char
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5059 (point-min)))}. This is written exactly the same way as it is written
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5060 in @code{beginning-of-buffer}. The expression moves the cursor to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5061 the minimum point in the buffer, that is, to the beginning of the buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5062 (or to the beginning of the accessible portion of the buffer). As a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5063 result of this, point is placed at the beginning of the buffer and mark
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5064 is set at the end of the buffer. The whole buffer is, therefore, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5065 region.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5066
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5067 @node append-to-buffer, Buffer Related Review, mark-whole-buffer, Buffer Walk Through
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5068 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5069 @section The Definition of @code{append-to-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5070 @findex append-to-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5071
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5072 The @code{append-to-buffer} command is more complex than the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5073 @code{mark-whole-buffer} command. What it does is copy the region
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5074 (that is, the part of the buffer between point and mark) from the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5075 current buffer to a specified buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5076
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5077 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5078 * append-to-buffer overview::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5079 * append interactive:: A two part interactive expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5080 * append-to-buffer body:: Incorporates a @code{let} expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5081 * append save-excursion:: How the @code{save-excursion} works.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5082 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5083
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5084 @node append-to-buffer overview, append interactive, append-to-buffer, append-to-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5085 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5086 @unnumberedsubsec An Overview of @code{append-to-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5087 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5088
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5089 @findex insert-buffer-substring
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5090 The @code{append-to-buffer} command uses the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5091 @code{insert-buffer-substring} function to copy the region.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5092 @code{insert-buffer-substring} is described by its name: it takes a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5093 string of characters from part of a buffer, a ``substring'', and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5094 inserts them into another buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5095
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5096 Most of @code{append-to-buffer} is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5097 concerned with setting up the conditions for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5098 @code{insert-buffer-substring} to work: the code must specify both the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5099 buffer to which the text will go, the window it comes from and goes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5100 to, and the region that will be copied.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5101
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5102 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5103 Here is the complete text of the function:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5104
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5105 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5106 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5107 (defun append-to-buffer (buffer start end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5108 "Append to specified buffer the text of the region.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5109 It is inserted into that buffer before its point.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5110 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5111
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5112 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5113 When calling from a program, give three arguments:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5114 BUFFER (or buffer name), START and END.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5115 START and END specify the portion of the current buffer to be copied."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5116 (interactive
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5117 (list (read-buffer "Append to buffer: " (other-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5118 (current-buffer) t))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5119 (region-beginning) (region-end)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5120 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5121 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5122 (let ((oldbuf (current-buffer)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5123 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5124 (let* ((append-to (get-buffer-create buffer))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5125 (windows (get-buffer-window-list append-to t t))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5126 point)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5127 (set-buffer append-to)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5128 (setq point (point))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5129 (barf-if-buffer-read-only)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5130 (insert-buffer-substring oldbuf start end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5131 (dolist (window windows)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5132 (when (= (window-point window) point)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5133 (set-window-point window (point))))))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5134 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5135 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5136
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5137 The function can be understood by looking at it as a series of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5138 filled-in templates.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5139
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5140 The outermost template is for the function definition. In this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5141 function, it looks like this (with several slots filled in):
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5142
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5143 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5144 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5145 (defun append-to-buffer (buffer start end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5146 "@var{documentation}@dots{}"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5147 (interactive @dots{})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5148 @var{body}@dots{})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5149 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5150 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5151
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5152 The first line of the function includes its name and three arguments.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5153 The arguments are the @code{buffer} to which the text will be copied, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5154 the @code{start} and @code{end} of the region in the current buffer that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5155 will be copied.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5156
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5157 The next part of the function is the documentation, which is clear and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5158 complete. As is conventional, the three arguments are written in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5159 upper case so you will notice them easily. Even better, they are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5160 described in the same order as in the argument list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5161
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5162 Note that the documentation distinguishes between a buffer and its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5163 name. (The function can handle either.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5164
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5165 @node append interactive, append-to-buffer body, append-to-buffer overview, append-to-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5166 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5167 @subsection The @code{append-to-buffer} Interactive Expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5168
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5169 Since the @code{append-to-buffer} function will be used interactively,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5170 the function must have an @code{interactive} expression. (For a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5171 review of @code{interactive}, see @ref{Interactive, , Making a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5172 Function Interactive}.) The expression reads as follows:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5173
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5174 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5175 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5176 (interactive
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5177 (list (read-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5178 "Append to buffer: "
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5179 (other-buffer (current-buffer) t))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5180 (region-beginning)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5181 (region-end)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5182 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5183 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5184
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5185 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5186 This expression is not one with letters standing for parts, as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5187 described earlier. Instead, it starts a list with these parts:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5188
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5189 The first part of the list is an expression to read the name of a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5190 buffer and return it as a string. That is @code{read-buffer}. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5191 function requires a prompt as its first argument, @samp{"Append to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5192 buffer: "}. Its second argument tells the command what value to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5193 provide if you don't specify anything.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5194
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5195 In this case that second argument is an expression containing the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5196 function @code{other-buffer}, an exception, and a @samp{t}, standing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5197 for true.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5198
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5199 The first argument to @code{other-buffer}, the exception, is yet
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5200 another function, @code{current-buffer}. That is not going to be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5201 returned. The second argument is the symbol for true, @code{t}. that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5202 tells @code{other-buffer} that it may show visible buffers (except in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5203 this case, it will not show the current buffer, which makes sense).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5204
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5205 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5206 The expression looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5207
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5208 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5209 (other-buffer (current-buffer) t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5210 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5211
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5212 The second and third arguments to the @code{list} expression are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5213 @code{(region-beginning)} and @code{(region-end)}. These two
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5214 functions specify the beginning and end of the text to be appended.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5215
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5216 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5217 Originally, the command used the letters @samp{B} and @samp{r}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5218 The whole @code{interactive} expression looked like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5219
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5220 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5221 (interactive "BAppend to buffer:@: \nr")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5222 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5223
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5224 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5225 But when that was done, the default value of the buffer switched to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5226 was invisible. That was not wanted.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5227
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5228 (The prompt was separated from the second argument with a newline,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5229 @samp{\n}. It was followed by an @samp{r} that told Emacs to bind the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5230 two arguments that follow the symbol @code{buffer} in the function's
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5231 argument list (that is, @code{start} and @code{end}) to the values of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5232 point and mark. That argument worked fine.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5233
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5234 @node append-to-buffer body, append save-excursion, append interactive, append-to-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5235 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5236 @subsection The Body of @code{append-to-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5237
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5238 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5239 in GNU Emacs 22 in /usr/local/src/emacs/lisp/simple.el
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5240
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5241 (defun append-to-buffer (buffer start end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5242 "Append to specified buffer the text of the region.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5243 It is inserted into that buffer before its point.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5244
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5245 When calling from a program, give three arguments:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5246 BUFFER (or buffer name), START and END.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5247 START and END specify the portion of the current buffer to be copied."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5248 (interactive
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5249 (list (read-buffer "Append to buffer: " (other-buffer (current-buffer) t))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5250 (region-beginning) (region-end)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5251 (let ((oldbuf (current-buffer)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5252 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5253 (let* ((append-to (get-buffer-create buffer))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5254 (windows (get-buffer-window-list append-to t t))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5255 point)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5256 (set-buffer append-to)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5257 (setq point (point))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5258 (barf-if-buffer-read-only)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5259 (insert-buffer-substring oldbuf start end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5260 (dolist (window windows)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5261 (when (= (window-point window) point)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5262 (set-window-point window (point))))))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5263 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5264
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5265 The body of the @code{append-to-buffer} function begins with @code{let}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5266
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5267 As we have seen before (@pxref{let, , @code{let}}), the purpose of a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5268 @code{let} expression is to create and give initial values to one or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5269 more variables that will only be used within the body of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5270 @code{let}. This means that such a variable will not be confused with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5271 any variable of the same name outside the @code{let} expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5272
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5273 We can see how the @code{let} expression fits into the function as a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5274 whole by showing a template for @code{append-to-buffer} with the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5275 @code{let} expression in outline:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5276
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5277 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5278 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5279 (defun append-to-buffer (buffer start end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5280 "@var{documentation}@dots{}"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5281 (interactive @dots{})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5282 (let ((@var{variable} @var{value}))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5283 @var{body}@dots{})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5284 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5285 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5286
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5287 The @code{let} expression has three elements:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5288
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5289 @enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5290 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5291 The symbol @code{let};
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5292
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5293 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5294 A varlist containing, in this case, a single two-element list,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5295 @code{(@var{variable} @var{value})};
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5296
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5297 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5298 The body of the @code{let} expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5299 @end enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5300
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5301 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5302 In the @code{append-to-buffer} function, the varlist looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5303
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5304 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5305 (oldbuf (current-buffer))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5306 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5307
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5308 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5309 In this part of the @code{let} expression, the one variable,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5310 @code{oldbuf}, is bound to the value returned by the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5311 @code{(current-buffer)} expression. The variable, @code{oldbuf}, is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5312 used to keep track of the buffer in which you are working and from
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5313 which you will copy.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5314
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5315 The element or elements of a varlist are surrounded by a set of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5316 parentheses so the Lisp interpreter can distinguish the varlist from
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5317 the body of the @code{let}. As a consequence, the two-element list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5318 within the varlist is surrounded by a circumscribing set of parentheses.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5319 The line looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5320
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5321 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5322 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5323 (let ((oldbuf (current-buffer)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5324 @dots{} )
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5325 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5326 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5327
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5328 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5329 The two parentheses before @code{oldbuf} might surprise you if you did
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5330 not realize that the first parenthesis before @code{oldbuf} marks the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5331 boundary of the varlist and the second parenthesis marks the beginning
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5332 of the two-element list, @code{(oldbuf (current-buffer))}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5333
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5334 @node append save-excursion, , append-to-buffer body, append-to-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5335 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5336 @subsection @code{save-excursion} in @code{append-to-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5337
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5338 The body of the @code{let} expression in @code{append-to-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5339 consists of a @code{save-excursion} expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5340
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5341 The @code{save-excursion} function saves the locations of point and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5342 mark, and restores them to those positions after the expressions in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5343 body of the @code{save-excursion} complete execution. In addition,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5344 @code{save-excursion} keeps track of the original buffer, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5345 restores it. This is how @code{save-excursion} is used in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5346 @code{append-to-buffer}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5347
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5348 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5349 @cindex Indentation for formatting
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5350 @cindex Formatting convention
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5351 Incidentally, it is worth noting here that a Lisp function is normally
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5352 formatted so that everything that is enclosed in a multi-line spread is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5353 indented more to the right than the first symbol. In this function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5354 definition, the @code{let} is indented more than the @code{defun}, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5355 the @code{save-excursion} is indented more than the @code{let}, like
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5356 this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5357
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5358 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5359 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5360 (defun @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5361 @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5362 @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5363 (let@dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5364 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5365 @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5366 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5367 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5368
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5369 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5370 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5371 This formatting convention makes it easy to see that the lines in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5372 the body of the @code{save-excursion} are enclosed by the parentheses
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5373 associated with @code{save-excursion}, just as the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5374 @code{save-excursion} itself is enclosed by the parentheses associated
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5375 with the @code{let}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5376
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5377 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5378 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5379 (let ((oldbuf (current-buffer)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5380 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5381 @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5382 (set-buffer @dots{})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5383 (insert-buffer-substring oldbuf start end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5384 @dots{}))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5385 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5386 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5387
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5388 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5389 The use of the @code{save-excursion} function can be viewed as a process
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5390 of filling in the slots of a template:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5391
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5392 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5393 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5394 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5395 @var{first-expression-in-body}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5396 @var{second-expression-in-body}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5397 @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5398 @var{last-expression-in-body})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5399 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5400 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5401
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5402 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5403 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5404 In this function, the body of the @code{save-excursion} contains only
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5405 one expression, the @code{let*} expression. You know about a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5406 @code{let} function. The @code{let*} function is different. It has a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5407 @samp{*} in its name. It enables Emacs to set each variable in its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5408 varlist in sequence, one after another.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5409
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5410 Its critical feature is that variables later in the varlist can make
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5411 use of the values to which Emacs set variables earlier in the varlist.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5412 @xref{fwd-para let, , The @code{let*} expression}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5413
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5414 We will skip functions like @code{let*} and focus on two: the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5415 @code{set-buffer} function and the @code{insert-buffer-substring}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5416 function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5417
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5418 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5419 In the old days, the @code{set-buffer} expression was simply
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5420
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5421 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5422 (set-buffer (get-buffer-create buffer))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5423 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5424
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5425 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5426 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5427 but now it is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5428
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5429 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5430 (set-buffer append-to)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5431 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5432
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5433 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5434 @code{append-to} is bound to @code{(get-buffer-create buffer)} earlier
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5435 on in the @code{let*} expression. That extra binding would not be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5436 necessary except for that @code{append-to} is used later in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5437 varlist as an argument to @code{get-buffer-window-list}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5438
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5439 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5440 in GNU Emacs 22
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5441
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5442 (let ((oldbuf (current-buffer)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5443 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5444 (let* ((append-to (get-buffer-create buffer))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5445 (windows (get-buffer-window-list append-to t t))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5446 point)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5447 (set-buffer append-to)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5448 (setq point (point))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5449 (barf-if-buffer-read-only)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5450 (insert-buffer-substring oldbuf start end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5451 (dolist (window windows)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5452 (when (= (window-point window) point)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5453 (set-window-point window (point))))))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5454 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5455
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5456 The @code{append-to-buffer} function definition inserts text from the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5457 buffer in which you are currently to a named buffer. It happens that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5458 @code{insert-buffer-substring} copies text from another buffer to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5459 current buffer, just the reverse---that is why the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5460 @code{append-to-buffer} definition starts out with a @code{let} that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5461 binds the local symbol @code{oldbuf} to the value returned by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5462 @code{current-buffer}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5463
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5464 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5465 The @code{insert-buffer-substring} expression looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5466
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5467 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5468 (insert-buffer-substring oldbuf start end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5469 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5470
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5471 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5472 The @code{insert-buffer-substring} function copies a string
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5473 @emph{from} the buffer specified as its first argument and inserts the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5474 string into the present buffer. In this case, the argument to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5475 @code{insert-buffer-substring} is the value of the variable created
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5476 and bound by the @code{let}, namely the value of @code{oldbuf}, which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5477 was the current buffer when you gave the @code{append-to-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5478 command.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5479
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5480 After @code{insert-buffer-substring} has done its work,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5481 @code{save-excursion} will restore the action to the original buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5482 and @code{append-to-buffer} will have done its job.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5483
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5484 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5485 Written in skeletal form, the workings of the body look like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5486
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5487 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5488 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5489 (let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5490 (save-excursion ; @r{Keep track of buffer.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5491 @var{change-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5492 @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5493
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5494 @var{change-back-to-original-buffer-when-finished}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5495 @var{let-the-local-meaning-of-}@code{oldbuf}@var{-disappear-when-finished}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5496 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5497 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5498
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5499 In summary, @code{append-to-buffer} works as follows: it saves the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5500 value of the current buffer in the variable called @code{oldbuf}. It
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5501 gets the new buffer (creating one if need be) and switches Emacs'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5502 attention to it. Using the value of @code{oldbuf}, it inserts the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5503 region of text from the old buffer into the new buffer; and then using
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5504 @code{save-excursion}, it brings you back to your original buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5505
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5506 In looking at @code{append-to-buffer}, you have explored a fairly
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5507 complex function. It shows how to use @code{let} and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5508 @code{save-excursion}, and how to change to and come back from another
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5509 buffer. Many function definitions use @code{let},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5510 @code{save-excursion}, and @code{set-buffer} this way.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5511
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5512 @node Buffer Related Review, Buffer Exercises, append-to-buffer, Buffer Walk Through
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5513 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5514 @section Review
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5515
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5516 Here is a brief summary of the various functions discussed in this chapter.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5517
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5518 @table @code
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5519 @item describe-function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5520 @itemx describe-variable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5521 Print the documentation for a function or variable.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5522 Conventionally bound to @kbd{C-h f} and @kbd{C-h v}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5523
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5524 @item find-tag
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5525 Find the file containing the source for a function or variable and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5526 switch buffers to it, positioning point at the beginning of the item.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5527 Conventionally bound to @kbd{M-.} (that's a period following the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5528 @key{META} key).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5529
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5530 @item save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5531 Save the location of point and mark and restore their values after the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5532 arguments to @code{save-excursion} have been evaluated. Also, remember
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5533 the current buffer and return to it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5534
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5535 @item push-mark
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5536 Set mark at a location and record the value of the previous mark on the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5537 mark ring. The mark is a location in the buffer that will keep its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5538 relative position even if text is added to or removed from the buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5539
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5540 @item goto-char
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5541 Set point to the location specified by the value of the argument, which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5542 can be a number, a marker, or an expression that returns the number of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5543 a position, such as @code{(point-min)}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5544
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5545 @item insert-buffer-substring
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5546 Copy a region of text from a buffer that is passed to the function as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5547 an argument and insert the region into the current buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5548
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5549 @item mark-whole-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5550 Mark the whole buffer as a region. Normally bound to @kbd{C-x h}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5551
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5552 @item set-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5553 Switch the attention of Emacs to another buffer, but do not change the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5554 window being displayed. Used when the program rather than a human is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5555 to work on a different buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5556
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5557 @item get-buffer-create
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5558 @itemx get-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5559 Find a named buffer or create one if a buffer of that name does not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5560 exist. The @code{get-buffer} function returns @code{nil} if the named
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5561 buffer does not exist.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5562 @end table
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5563
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5564 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5565 @node Buffer Exercises, , Buffer Related Review, Buffer Walk Through
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5566 @section Exercises
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5567
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5568 @itemize @bullet
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5569 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5570 Write your own @code{simplified-end-of-buffer} function definition;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5571 then test it to see whether it works.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5572
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5573 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5574 Use @code{if} and @code{get-buffer} to write a function that prints a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5575 message telling you whether a buffer exists.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5576
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5577 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5578 Using @code{find-tag}, find the source for the @code{copy-to-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5579 function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5580 @end itemize
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5581
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5582 @node More Complex, Narrowing & Widening, Buffer Walk Through, Top
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5583 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5584 @chapter A Few More Complex Functions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5585
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5586 In this chapter, we build on what we have learned in previous chapters
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5587 by looking at more complex functions. The @code{copy-to-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5588 function illustrates use of two @code{save-excursion} expressions in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5589 one definition, while the @code{insert-buffer} function illustrates
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5590 use of an asterisk in an @code{interactive} expression, use of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5591 @code{or}, and the important distinction between a name and the object
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5592 to which the name refers.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5593
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5594 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5595 * copy-to-buffer:: With @code{set-buffer}, @code{get-buffer-create}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5596 * insert-buffer:: Read-only, and with @code{or}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5597 * beginning-of-buffer:: Shows @code{goto-char},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5598 @code{point-min}, and @code{push-mark}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5599 * Second Buffer Related Review::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5600 * optional Exercise::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5601 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5602
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5603 @node copy-to-buffer, insert-buffer, More Complex, More Complex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5604 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5605 @section The Definition of @code{copy-to-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5606 @findex copy-to-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5607
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5608 After understanding how @code{append-to-buffer} works, it is easy to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5609 understand @code{copy-to-buffer}. This function copies text into a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5610 buffer, but instead of adding to the second buffer, it replaces all the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5611 previous text in the second buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5612
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5613 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5614 The body of @code{copy-to-buffer} looks like this,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5615
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5616 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5617 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5618 @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5619 (interactive "BCopy to buffer: \nr")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5620 (let ((oldbuf (current-buffer)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5621 (with-current-buffer (get-buffer-create buffer)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5622 (barf-if-buffer-read-only)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5623 (erase-buffer)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5624 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5625 (insert-buffer-substring oldbuf start end)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5626 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5627 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5628
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5629 The @code{copy-to-buffer} function has a simpler @code{interactive}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5630 expression than @code{append-to-buffer}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5631
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5632 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5633 The definition then says
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5634
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5635 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5636 (with-current-buffer (get-buffer-create buffer) @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5637 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5638
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5639 First, look at the earliest inner expression; that is evaluated first.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5640 That expression starts with @code{get-buffer-create buffer}. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5641 function tells the computer to use the buffer with the name specified
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5642 as the one to which you are copying, or if such a buffer does not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5643 exist, to create it. Then, the @code{with-current-buffer} function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5644 evaluates its body with that buffer temporarily current.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5645
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5646 (This demonstrates another way to shift the computer's attention but
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5647 not the user's. The @code{append-to-buffer} function showed how to do
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5648 the same with @code{save-excursion} and @code{set-buffer}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5649 @code{with-current-buffer} is a newer, and arguably easier,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5650 mechanism.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5651
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5652 The @code{barf-if-buffer-read-only} function sends you an error
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5653 message saying the buffer is read-only if you cannot modify it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5654
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5655 The next line has the @code{erase-buffer} function as its sole
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5656 contents. That function erases the buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5657
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5658 Finally, the last two lines contain the @code{save-excursion}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5659 expression with @code{insert-buffer-substring} as its body.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5660 The @code{insert-buffer-substring} expression copies the text from
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5661 the buffer you are in (and you have not seen the computer shift its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5662 attention, so you don't know that that buffer is now called
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5663 @code{oldbuf}).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5664
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5665 Incidentally, this is what is meant by `replacement'. To replace text,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5666 Emacs erases the previous text and then inserts new text.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5667
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5668 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5669 In outline, the body of @code{copy-to-buffer} looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5670
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5671 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5672 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5673 (let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5674 (@var{with-the-buffer-you-are-copying-to}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5675 (@var{but-do-not-erase-or-copy-to-a-read-only-buffer})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5676 (erase-buffer)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5677 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5678 @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer})))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5679 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5680 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5681
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5682 @node insert-buffer, beginning-of-buffer, copy-to-buffer, More Complex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5683 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5684 @section The Definition of @code{insert-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5685 @findex insert-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5686
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5687 @code{insert-buffer} is yet another buffer-related function. This
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5688 command copies another buffer @emph{into} the current buffer. It is the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5689 reverse of @code{append-to-buffer} or @code{copy-to-buffer}, since they
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5690 copy a region of text @emph{from} the current buffer to another buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5691
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5692 Here is a discussion based on the original code. The code was
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5693 simplified in 2003 and is harder to understand.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5694
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5695 (@xref{New insert-buffer, , New Body for @code{insert-buffer}}, to see
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5696 a discussion of the new body.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5697
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5698 In addition, this code illustrates the use of @code{interactive} with a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5699 buffer that might be @dfn{read-only} and the important distinction
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5700 between the name of an object and the object actually referred to.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5701
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5702 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5703 * insert-buffer code::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5704 * insert-buffer interactive:: When you can read, but not write.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5705 * insert-buffer body:: The body has an @code{or} and a @code{let}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5706 * if & or:: Using an @code{if} instead of an @code{or}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5707 * Insert or:: How the @code{or} expression works.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5708 * Insert let:: Two @code{save-excursion} expressions.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5709 * New insert-buffer::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5710 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5711
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5712 @node insert-buffer code, insert-buffer interactive, insert-buffer, insert-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5713 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5714 @unnumberedsubsec The Code for @code{insert-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5715 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5716
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5717 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5718 Here is the earlier code:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5719
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5720 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5721 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5722 (defun insert-buffer (buffer)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5723 "Insert after point the contents of BUFFER.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5724 Puts mark after the inserted text.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5725 BUFFER may be a buffer or a buffer name."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5726 (interactive "*bInsert buffer:@: ")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5727 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5728 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5729 (or (bufferp buffer)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5730 (setq buffer (get-buffer buffer)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5731 (let (start end newmark)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5732 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5733 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5734 (set-buffer buffer)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5735 (setq start (point-min) end (point-max)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5736 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5737 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5738 (insert-buffer-substring buffer start end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5739 (setq newmark (point)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5740 (push-mark newmark)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5741 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5742 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5743
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5744 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5745 As with other function definitions, you can use a template to see an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5746 outline of the function:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5747
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5748 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5749 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5750 (defun insert-buffer (buffer)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5751 "@var{documentation}@dots{}"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5752 (interactive "*bInsert buffer:@: ")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5753 @var{body}@dots{})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5754 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5755 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5756
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5757 @node insert-buffer interactive, insert-buffer body, insert-buffer code, insert-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5758 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5759 @subsection The Interactive Expression in @code{insert-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5760 @findex interactive, @r{example use of}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5761
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5762 In @code{insert-buffer}, the argument to the @code{interactive}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5763 declaration has two parts, an asterisk, @samp{*}, and @samp{bInsert
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5764 buffer:@: }.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5765
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5766 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5767 * Read-only buffer:: When a buffer cannot be modified.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5768 * b for interactive:: An existing buffer or else its name.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5769 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5770
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5771 @node Read-only buffer, b for interactive, insert-buffer interactive, insert-buffer interactive
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5772 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5773 @unnumberedsubsubsec A Read-only Buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5774 @cindex Read-only buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5775 @cindex Asterisk for read-only buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5776 @findex * @r{for read-only buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5777
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5778 The asterisk is for the situation when the current buffer is a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5779 read-only buffer---a buffer that cannot be modified. If
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5780 @code{insert-buffer} is called when the current buffer is read-only, a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5781 message to this effect is printed in the echo area and the terminal
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5782 may beep or blink at you; you will not be permitted to insert anything
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5783 into current buffer. The asterisk does not need to be followed by a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5784 newline to separate it from the next argument.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5785
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5786 @node b for interactive, , Read-only buffer, insert-buffer interactive
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5787 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5788 @unnumberedsubsubsec @samp{b} in an Interactive Expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5789
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5790 The next argument in the interactive expression starts with a lower
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5791 case @samp{b}. (This is different from the code for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5792 @code{append-to-buffer}, which uses an upper-case @samp{B}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5793 @xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5794 The lower-case @samp{b} tells the Lisp interpreter that the argument
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5795 for @code{insert-buffer} should be an existing buffer or else its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5796 name. (The upper-case @samp{B} option provides for the possibility
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5797 that the buffer does not exist.) Emacs will prompt you for the name
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5798 of the buffer, offering you a default buffer, with name completion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5799 enabled. If the buffer does not exist, you receive a message that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5800 says ``No match''; your terminal may beep at you as well.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5801
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5802 The new and simplified code generates a list for @code{interactive}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5803 It uses the @code{barf-if-buffer-read-only} and @code{read-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5804 functions with which we are already familiar and the @code{progn}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5805 special form with which we are not. (It will be described later.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5806
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5807 @node insert-buffer body, if & or, insert-buffer interactive, insert-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5808 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5809 @subsection The Body of the @code{insert-buffer} Function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5810
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5811 The body of the @code{insert-buffer} function has two major parts: an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5812 @code{or} expression and a @code{let} expression. The purpose of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5813 @code{or} expression is to ensure that the argument @code{buffer} is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5814 bound to a buffer and not just the name of a buffer. The body of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5815 @code{let} expression contains the code which copies the other buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5816 into the current buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5817
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5818 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5819 In outline, the two expressions fit into the @code{insert-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5820 function like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5821
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5822 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5823 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5824 (defun insert-buffer (buffer)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5825 "@var{documentation}@dots{}"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5826 (interactive "*bInsert buffer:@: ")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5827 (or @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5828 @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5829 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5830 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5831 (let (@var{varlist})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5832 @var{body-of-}@code{let}@dots{} )
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5833 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5834 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5835
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5836 To understand how the @code{or} expression ensures that the argument
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5837 @code{buffer} is bound to a buffer and not to the name of a buffer, it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5838 is first necessary to understand the @code{or} function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5839
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5840 Before doing this, let me rewrite this part of the function using
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5841 @code{if} so that you can see what is done in a manner that will be familiar.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5842
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5843 @node if & or, Insert or, insert-buffer body, insert-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5844 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5845 @subsection @code{insert-buffer} With an @code{if} Instead of an @code{or}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5846
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5847 The job to be done is to make sure the value of @code{buffer} is a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5848 buffer itself and not the name of a buffer. If the value is the name,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5849 then the buffer itself must be got.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5850
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5851 You can imagine yourself at a conference where an usher is wandering
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5852 around holding a list with your name on it and looking for you: the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5853 usher is ``bound'' to your name, not to you; but when the usher finds
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5854 you and takes your arm, the usher becomes ``bound'' to you.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5855
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5856 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5857 In Lisp, you might describe this situation like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5858
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5859 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5860 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5861 (if (not (holding-on-to-guest))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5862 (find-and-take-arm-of-guest))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5863 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5864 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5865
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5866 We want to do the same thing with a buffer---if we do not have the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5867 buffer itself, we want to get it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5868
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5869 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5870 Using a predicate called @code{bufferp} that tells us whether we have a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5871 buffer (rather than its name), we can write the code like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5872
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5873 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5874 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5875 (if (not (bufferp buffer)) ; @r{if-part}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5876 (setq buffer (get-buffer buffer))) ; @r{then-part}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5877 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5878 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5879
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5880 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5881 Here, the true-or-false-test of the @code{if} expression is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5882 @w{@code{(not (bufferp buffer))}}; and the then-part is the expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5883 @w{@code{(setq buffer (get-buffer buffer))}}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5884
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5885 In the test, the function @code{bufferp} returns true if its argument is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5886 a buffer---but false if its argument is the name of the buffer. (The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5887 last character of the function name @code{bufferp} is the character
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5888 @samp{p}; as we saw earlier, such use of @samp{p} is a convention that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5889 indicates that the function is a predicate, which is a term that means
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5890 that the function will determine whether some property is true or false.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5891 @xref{Wrong Type of Argument, , Using the Wrong Type Object as an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5892 Argument}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5893
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5894 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5895 The function @code{not} precedes the expression @code{(bufferp buffer)},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5896 so the true-or-false-test looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5897
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5898 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5899 (not (bufferp buffer))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5900 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5901
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5902 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5903 @code{not} is a function that returns true if its argument is false
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5904 and false if its argument is true. So if @code{(bufferp buffer)}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5905 returns true, the @code{not} expression returns false and vice-verse:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5906 what is ``not true'' is false and what is ``not false'' is true.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5907
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5908 Using this test, the @code{if} expression works as follows: when the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5909 value of the variable @code{buffer} is actually a buffer rather than
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5910 its name, the true-or-false-test returns false and the @code{if}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5911 expression does not evaluate the then-part. This is fine, since we do
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5912 not need to do anything to the variable @code{buffer} if it really is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5913 a buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5914
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5915 On the other hand, when the value of @code{buffer} is not a buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5916 itself, but the name of a buffer, the true-or-false-test returns true
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5917 and the then-part of the expression is evaluated. In this case, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5918 then-part is @code{(setq buffer (get-buffer buffer))}. This
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5919 expression uses the @code{get-buffer} function to return an actual
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5920 buffer itself, given its name. The @code{setq} then sets the variable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5921 @code{buffer} to the value of the buffer itself, replacing its previous
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5922 value (which was the name of the buffer).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5923
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5924 @node Insert or, Insert let, if & or, insert-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5925 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5926 @subsection The @code{or} in the Body
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5927
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5928 The purpose of the @code{or} expression in the @code{insert-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5929 function is to ensure that the argument @code{buffer} is bound to a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5930 buffer and not just to the name of a buffer. The previous section shows
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5931 how the job could have been done using an @code{if} expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5932 However, the @code{insert-buffer} function actually uses @code{or}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5933 To understand this, it is necessary to understand how @code{or} works.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5934
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5935 @findex or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5936 An @code{or} function can have any number of arguments. It evaluates
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5937 each argument in turn and returns the value of the first of its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5938 arguments that is not @code{nil}. Also, and this is a crucial feature
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5939 of @code{or}, it does not evaluate any subsequent arguments after
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5940 returning the first non-@code{nil} value.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5941
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5942 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5943 The @code{or} expression looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5944
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5945 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5946 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5947 (or (bufferp buffer)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5948 (setq buffer (get-buffer buffer)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5949 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5950 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5951
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5952 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5953 The first argument to @code{or} is the expression @code{(bufferp buffer)}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5954 This expression returns true (a non-@code{nil} value) if the buffer is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5955 actually a buffer, and not just the name of a buffer. In the @code{or}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5956 expression, if this is the case, the @code{or} expression returns this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5957 true value and does not evaluate the next expression---and this is fine
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5958 with us, since we do not want to do anything to the value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5959 @code{buffer} if it really is a buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5960
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5961 On the other hand, if the value of @code{(bufferp buffer)} is @code{nil},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5962 which it will be if the value of @code{buffer} is the name of a buffer,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5963 the Lisp interpreter evaluates the next element of the @code{or}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5964 expression. This is the expression @code{(setq buffer (get-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5965 buffer))}. This expression returns a non-@code{nil} value, which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5966 is the value to which it sets the variable @code{buffer}---and this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5967 value is a buffer itself, not the name of a buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5968
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5969 The result of all this is that the symbol @code{buffer} is always
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5970 bound to a buffer itself rather than to the name of a buffer. All
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5971 this is necessary because the @code{set-buffer} function in a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5972 following line only works with a buffer itself, not with the name to a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5973 buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5974
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5975 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5976 Incidentally, using @code{or}, the situation with the usher would be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5977 written like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5978
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5979 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5980 (or (holding-on-to-guest) (find-and-take-arm-of-guest))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5981 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5982
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5983 @node Insert let, New insert-buffer, Insert or, insert-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5984 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5985 @subsection The @code{let} Expression in @code{insert-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5986
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5987 After ensuring that the variable @code{buffer} refers to a buffer itself
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5988 and not just to the name of a buffer, the @code{insert-buffer function}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5989 continues with a @code{let} expression. This specifies three local
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5990 variables, @code{start}, @code{end}, and @code{newmark} and binds them
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5991 to the initial value @code{nil}. These variables are used inside the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5992 remainder of the @code{let} and temporarily hide any other occurrence of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5993 variables of the same name in Emacs until the end of the @code{let}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5994
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5995 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5996 The body of the @code{let} contains two @code{save-excursion}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5997 expressions. First, we will look at the inner @code{save-excursion}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5998 expression in detail. The expression looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5999
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6000 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6001 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6002 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6003 (set-buffer buffer)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6004 (setq start (point-min) end (point-max)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6005 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6006 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6007
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6008 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6009 The expression @code{(set-buffer buffer)} changes Emacs' attention
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6010 from the current buffer to the one from which the text will copied.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6011 In that buffer, the variables @code{start} and @code{end} are set to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6012 the beginning and end of the buffer, using the commands
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6013 @code{point-min} and @code{point-max}. Note that we have here an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6014 illustration of how @code{setq} is able to set two variables in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6015 same expression. The first argument of @code{setq} is set to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6016 value of its second, and its third argument is set to the value of its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6017 fourth.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6018
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6019 After the body of the inner @code{save-excursion} is evaluated, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6020 @code{save-excursion} restores the original buffer, but @code{start} and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6021 @code{end} remain set to the values of the beginning and end of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6022 buffer from which the text will be copied.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6023
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6024 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6025 The outer @code{save-excursion} expression looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6026
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6027 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6028 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6029 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6030 (@var{inner-}@code{save-excursion}@var{-expression}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6031 (@var{go-to-new-buffer-and-set-}@code{start}@var{-and-}@code{end})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6032 (insert-buffer-substring buffer start end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6033 (setq newmark (point)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6034 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6035 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6036
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6037 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6038 The @code{insert-buffer-substring} function copies the text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6039 @emph{into} the current buffer @emph{from} the region indicated by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6040 @code{start} and @code{end} in @code{buffer}. Since the whole of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6041 second buffer lies between @code{start} and @code{end}, the whole of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6042 the second buffer is copied into the buffer you are editing. Next,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6043 the value of point, which will be at the end of the inserted text, is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6044 recorded in the variable @code{newmark}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6045
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6046 After the body of the outer @code{save-excursion} is evaluated, point
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6047 and mark are relocated to their original places.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6048
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6049 However, it is convenient to locate a mark at the end of the newly
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6050 inserted text and locate point at its beginning. The @code{newmark}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6051 variable records the end of the inserted text. In the last line of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6052 the @code{let} expression, the @code{(push-mark newmark)} expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6053 function sets a mark to this location. (The previous location of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6054 mark is still accessible; it is recorded on the mark ring and you can
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6055 go back to it with @kbd{C-u C-@key{SPC}}.) Meanwhile, point is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6056 located at the beginning of the inserted text, which is where it was
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6057 before you called the insert function, the position of which was saved
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6058 by the first @code{save-excursion}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6059
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6060 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6061 The whole @code{let} expression looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6062
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6063 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6064 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6065 (let (start end newmark)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6066 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6067 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6068 (set-buffer buffer)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6069 (setq start (point-min) end (point-max)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6070 (insert-buffer-substring buffer start end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6071 (setq newmark (point)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6072 (push-mark newmark))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6073 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6074 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6075
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6076 Like the @code{append-to-buffer} function, the @code{insert-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6077 function uses @code{let}, @code{save-excursion}, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6078 @code{set-buffer}. In addition, the function illustrates one way to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6079 use @code{or}. All these functions are building blocks that we will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6080 find and use again and again.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6081
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6082 @node New insert-buffer, , Insert let, insert-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6083 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6084 @subsection New Body for @code{insert-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6085 @findex insert-buffer, new version body
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6086 @findex new version body for insert-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6087
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6088 The body in the GNU Emacs 22 version is more confusing than the original.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6089
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6090 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6091 It consists of two expressions,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6092
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6093 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6094 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6095 (push-mark
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6096 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6097 (insert-buffer-substring (get-buffer buffer))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6098 (point)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6099
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6100 nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6101 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6102 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6103
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6104 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6105 except, and this is what confuses novices, very important work is done
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6106 inside the @code{push-mark} expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6107
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6108 The @code{get-buffer} function returns a buffer with the name
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6109 provided. You will note that the function is @emph{not} called
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6110 @code{get-buffer-create}; it does not create a buffer if one does not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6111 already exist. The buffer returned by @code{get-buffer}, an existing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6112 buffer, is passed to @code{insert-buffer-substring}, which inserts the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6113 whole of the buffer (since you did not specify anything else).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6114
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6115 The location into which the buffer is inserted is recorded by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6116 @code{push-mark}. Then the function returns @code{nil}, the value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6117 its last command. Put another way, the @code{insert-buffer} function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6118 exists only to produce a side effect, inserting another buffer, not to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6119 return any value.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6120
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6121 @node beginning-of-buffer, Second Buffer Related Review, insert-buffer, More Complex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6122 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6123 @section Complete Definition of @code{beginning-of-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6124 @findex beginning-of-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6125
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6126 The basic structure of the @code{beginning-of-buffer} function has
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6127 already been discussed. (@xref{simplified-beginning-of-buffer, , A
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6128 Simplified @code{beginning-of-buffer} Definition}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6129 This section describes the complex part of the definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6130
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6131 As previously described, when invoked without an argument,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6132 @code{beginning-of-buffer} moves the cursor to the beginning of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6133 buffer (in truth, the beginning of the accessible portion of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6134 buffer), leaving the mark at the previous position. However, when the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6135 command is invoked with a number between one and ten, the function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6136 considers that number to be a fraction of the length of the buffer,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6137 measured in tenths, and Emacs moves the cursor that fraction of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6138 way from the beginning of the buffer. Thus, you can either call this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6139 function with the key command @kbd{M-<}, which will move the cursor to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6140 the beginning of the buffer, or with a key command such as @kbd{C-u 7
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6141 M-<} which will move the cursor to a point 70% of the way through the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6142 buffer. If a number bigger than ten is used for the argument, it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6143 moves to the end of the buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6144
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6145 The @code{beginning-of-buffer} function can be called with or without an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6146 argument. The use of the argument is optional.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6147
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6148 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6149 * Optional Arguments::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6150 * beginning-of-buffer opt arg:: Example with optional argument.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6151 * beginning-of-buffer complete::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6152 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6153
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6154 @node Optional Arguments, beginning-of-buffer opt arg, beginning-of-buffer, beginning-of-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6155 @subsection Optional Arguments
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6156
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6157 Unless told otherwise, Lisp expects that a function with an argument in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6158 its function definition will be called with a value for that argument.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6159 If that does not happen, you get an error and a message that says
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6160 @samp{Wrong number of arguments}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6161
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6162 @cindex Optional arguments
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6163 @cindex Keyword
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6164 @findex optional
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6165 However, optional arguments are a feature of Lisp: a particular
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6166 @dfn{keyword} is used to tell the Lisp interpreter that an argument is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6167 optional. The keyword is @code{&optional}. (The @samp{&} in front of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6168 @samp{optional} is part of the keyword.) In a function definition, if
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6169 an argument follows the keyword @code{&optional}, no value need be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6170 passed to that argument when the function is called.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6171
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6172 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6173 The first line of the function definition of @code{beginning-of-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6174 therefore looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6175
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6176 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6177 (defun beginning-of-buffer (&optional arg)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6178 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6179
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6180 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6181 In outline, the whole function looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6182
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6183 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6184 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6185 (defun beginning-of-buffer (&optional arg)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6186 "@var{documentation}@dots{}"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6187 (interactive "P")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6188 (or (@var{is-the-argument-a-cons-cell} arg)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6189 (and @var{are-both-transient-mark-mode-and-mark-active-true})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6190 (push-mark))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6191 (let (@var{determine-size-and-set-it})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6192 (goto-char
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6193 (@var{if-there-is-an-argument}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6194 @var{figure-out-where-to-go}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6195 @var{else-go-to}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6196 (point-min))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6197 @var{do-nicety}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6198 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6199 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6201 The function is similar to the @code{simplified-beginning-of-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6202 function except that the @code{interactive} expression has @code{"P"}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6203 as an argument and the @code{goto-char} function is followed by an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6204 if-then-else expression that figures out where to put the cursor if
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6205 there is an argument that is not a cons cell.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6206
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6207 (Since I do not explain a cons cell for many more chapters, please
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6208 consider ignoring the function @code{consp}. @xref{List
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6209 Implementation, , How Lists are Implemented}, and @ref{Cons Cell Type,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6210 , Cons Cell and List Types, elisp, The GNU Emacs Lisp Reference
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6211 Manual}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6212
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6213 The @code{"P"} in the @code{interactive} expression tells Emacs to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6214 pass a prefix argument, if there is one, to the function in raw form.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6215 A prefix argument is made by typing the @key{META} key followed by a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6216 number, or by typing @kbd{C-u} and then a number. (If you don't type
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6217 a number, @kbd{C-u} defaults to a cons cell with a 4. A lowercase
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6218 @code{"p"} in the @code{interactive} expression causes the function to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6219 convert a prefix arg to a number.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6220
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6221 The true-or-false-test of the @code{if} expression looks complex, but
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6222 it is not: it checks whether @code{arg} has a value that is not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6223 @code{nil} and whether it is a cons cell. (That is what @code{consp}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6224 does; it checks whether its argument is a cons cell.) If @code{arg}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6225 has a value that is not @code{nil} (and is not a cons cell), which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6226 will be the case if @code{beginning-of-buffer} is called with a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6227 numeric argument, then this true-or-false-test will return true and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6228 the then-part of the @code{if} expression will be evaluated. On the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6229 other hand, if @code{beginning-of-buffer} is not called with an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6230 argument, the value of @code{arg} will be @code{nil} and the else-part
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6231 of the @code{if} expression will be evaluated. The else-part is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6232 simply @code{point-min}, and when this is the outcome, the whole
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6233 @code{goto-char} expression is @code{(goto-char (point-min))}, which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6234 is how we saw the @code{beginning-of-buffer} function in its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6235 simplified form.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6236
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6237 @node beginning-of-buffer opt arg, beginning-of-buffer complete, Optional Arguments, beginning-of-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6238 @subsection @code{beginning-of-buffer} with an Argument
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6239
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6240 When @code{beginning-of-buffer} is called with an argument, an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6241 expression is evaluated which calculates what value to pass to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6242 @code{goto-char}. This expression is rather complicated at first sight.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6243 It includes an inner @code{if} expression and much arithmetic. It looks
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6244 like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6245
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6246 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6247 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6248 (if (> (buffer-size) 10000)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6249 ;; @r{Avoid overflow for large buffer sizes!}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6250 (* (prefix-numeric-value arg)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6251 (/ size 10))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6252 (/
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6253 (+ 10
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6254 (*
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6255 size (prefix-numeric-value arg))) 10)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6256 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6257 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6258
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6259 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6260 * Disentangle beginning-of-buffer::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6261 * Large buffer case::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6262 * Small buffer case::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6263 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6264
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6265 @node Disentangle beginning-of-buffer, Large buffer case, beginning-of-buffer opt arg, beginning-of-buffer opt arg
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6266 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6267 @unnumberedsubsubsec Disentangle @code{beginning-of-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6268 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6269
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6270 Like other complex-looking expressions, the conditional expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6271 within @code{beginning-of-buffer} can be disentangled by looking at it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6272 as parts of a template, in this case, the template for an if-then-else
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6273 expression. In skeletal form, the expression looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6274
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6275 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6276 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6277 (if (@var{buffer-is-large}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6278 @var{divide-buffer-size-by-10-and-multiply-by-arg}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6279 @var{else-use-alternate-calculation}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6280 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6281 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6282
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6283 The true-or-false-test of this inner @code{if} expression checks the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6284 size of the buffer. The reason for this is that the old version 18
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6285 Emacs used numbers that are no bigger than eight million or so and in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6286 the computation that followed, the programmer feared that Emacs might
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6287 try to use over-large numbers if the buffer were large. The term
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6288 `overflow', mentioned in the comment, means numbers that are over
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6289 large. More recent versions of Emacs use larger numbers, but this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6290 code has not been touched, if only because people now look at buffers
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6291 that are far, far larger than ever before.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6292
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6293 There are two cases: if the buffer is large and if it is not.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6294
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6295 @node Large buffer case, Small buffer case, Disentangle beginning-of-buffer, beginning-of-buffer opt arg
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6296 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6297 @unnumberedsubsubsec What happens in a large buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6298
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6299 In @code{beginning-of-buffer}, the inner @code{if} expression tests
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6300 whether the size of the buffer is greater than 10,000 characters. To do
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6301 this, it uses the @code{>} function and the computation of @code{size}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6302 that comes from the let expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6303
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6304 In the old days, the function @code{buffer-size} was used. Not only
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6305 was that function called several times, it gave the size of the whole
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6306 buffer, not the accessible part. The computation makes much more
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6307 sense when it handles just the accessible part. (@xref{Narrowing &
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6308 Widening, , Narrowing and Widening}, for more information on focusing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6309 attention to an `accessible' part.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6310
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6311 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6312 The line looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6313
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6314 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6315 (if (> size 10000)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6316 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6317
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6318 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6319 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6320 When the buffer is large, the then-part of the @code{if} expression is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6321 evaluated. It reads like this (after formatting for easy reading):
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6322
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6323 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6324 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6325 (*
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6326 (prefix-numeric-value arg)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6327 (/ size 10))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6328 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6329 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6330
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6331 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6332 This expression is a multiplication, with two arguments to the function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6333 @code{*}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6334
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6335 The first argument is @code{(prefix-numeric-value arg)}. When
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6336 @code{"P"} is used as the argument for @code{interactive}, the value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6337 passed to the function as its argument is passed a ``raw prefix
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6338 argument'', and not a number. (It is a number in a list.) To perform
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6339 the arithmetic, a conversion is necessary, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6340 @code{prefix-numeric-value} does the job.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6341
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6342 @findex / @r{(division)}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6343 @cindex Division
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6344 The second argument is @code{(/ size 10)}. This expression divides
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6345 the numeric value by ten --- the numeric value of the size of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6346 accessible portion of the buffer. This produces a number that tells
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6347 how many characters make up one tenth of the buffer size. (In Lisp,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6348 @code{/} is used for division, just as @code{*} is used for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6349 multiplication.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6350
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6351 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6352 In the multiplication expression as a whole, this amount is multiplied
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6353 by the value of the prefix argument---the multiplication looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6354
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6355 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6356 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6357 (* @var{numeric-value-of-prefix-arg}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6358 @var{number-of-characters-in-one-tenth-of-the-accessible-buffer})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6359 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6360 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6361
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6362 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6363 If, for example, the prefix argument is @samp{7}, the one-tenth value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6364 will be multiplied by 7 to give a position 70% of the way through.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6365
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6366 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6367 The result of all this is that if the accessible portion of the buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6368 is large, the @code{goto-char} expression reads like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6369
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6370 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6371 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6372 (goto-char (* (prefix-numeric-value arg)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6373 (/ size 10)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6374 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6375 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6376
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6377 This puts the cursor where we want it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6378
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6379 @node Small buffer case, , Large buffer case, beginning-of-buffer opt arg
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6380 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6381 @unnumberedsubsubsec What happens in a small buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6382
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6383 If the buffer contains fewer than 10,000 characters, a slightly
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6384 different computation is performed. You might think this is not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6385 necessary, since the first computation could do the job. However, in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6386 a small buffer, the first method may not put the cursor on exactly the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6387 desired line; the second method does a better job.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6388
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6389 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6390 The code looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6391
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6392 @c Keep this on one line.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6393 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6394 (/ (+ 10 (* size (prefix-numeric-value arg))) 10))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6395 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6396
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6397 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6398 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6399 This is code in which you figure out what happens by discovering how the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6400 functions are embedded in parentheses. It is easier to read if you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6401 reformat it with each expression indented more deeply than its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6402 enclosing expression:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6403
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6404 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6405 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6406 (/
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6407 (+ 10
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6408 (*
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6409 size
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6410 (prefix-numeric-value arg)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6411 10))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6412 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6413 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6414
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6415 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6416 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6417 Looking at parentheses, we see that the innermost operation is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6418 @code{(prefix-numeric-value arg)}, which converts the raw argument to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6419 a number. In the following expression, this number is multiplied by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6420 the size of the accessible portion of the buffer:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6421
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6422 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6423 (* size (prefix-numeric-value arg))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6424 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6425
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6426 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6427 This multiplication creates a number that may be larger than the size of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6428 the buffer---seven times larger if the argument is 7, for example. Ten
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6429 is then added to this number and finally the large number is divided by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6430 ten to provide a value that is one character larger than the percentage
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6431 position in the buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6432
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6433 The number that results from all this is passed to @code{goto-char} and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6434 the cursor is moved to that point.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6435
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6436 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6437 @node beginning-of-buffer complete, , beginning-of-buffer opt arg, beginning-of-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6438 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6439 @subsection The Complete @code{beginning-of-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6440
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6441 @need 1000
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6442 Here is the complete text of the @code{beginning-of-buffer} function:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6443 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6444
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6445 @c In GNU Emacs 22
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6446 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6447 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6448 (defun beginning-of-buffer (&optional arg)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6449 "Move point to the beginning of the buffer;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6450 leave mark at previous position.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6451 With \\[universal-argument] prefix,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6452 do not set mark at previous position.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6453 With numeric arg N,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6454 put point N/10 of the way from the beginning.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6455
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6456 If the buffer is narrowed,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6457 this command uses the beginning and size
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6458 of the accessible part of the buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6459 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6460
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6461 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6462 Don't use this command in Lisp programs!
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6463 \(goto-char (point-min)) is faster
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6464 and avoids clobbering the mark."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6465 (interactive "P")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6466 (or (consp arg)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6467 (and transient-mark-mode mark-active)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6468 (push-mark))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6469 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6470 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6471 (let ((size (- (point-max) (point-min))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6472 (goto-char (if (and arg (not (consp arg)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6473 (+ (point-min)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6474 (if (> size 10000)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6475 ;; Avoid overflow for large buffer sizes!
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6476 (* (prefix-numeric-value arg)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6477 (/ size 10))
98525
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
6478 (/ (+ 10 (* size (prefix-numeric-value arg)))
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
6479 10)))
83955
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6480 (point-min))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6481 (if arg (forward-line 1)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6482 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6483 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6484
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6485 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6486 From before GNU Emacs 22
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6487 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6488 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6489 (defun beginning-of-buffer (&optional arg)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6490 "Move point to the beginning of the buffer;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6491 leave mark at previous position.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6492 With arg N, put point N/10 of the way
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6493 from the true beginning.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6494 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6495 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6496 Don't use this in Lisp programs!
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6497 \(goto-char (point-min)) is faster
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6498 and does not set the mark."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6499 (interactive "P")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6500 (push-mark)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6501 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6502 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6503 (goto-char
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6504 (if arg
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6505 (if (> (buffer-size) 10000)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6506 ;; @r{Avoid overflow for large buffer sizes!}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6507 (* (prefix-numeric-value arg)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6508 (/ (buffer-size) 10))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6509 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6510 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6511 (/ (+ 10 (* (buffer-size)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6512 (prefix-numeric-value arg)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6513 10))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6514 (point-min)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6515 (if arg (forward-line 1)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6516 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6517 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6518 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6519
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6520 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6521 Except for two small points, the previous discussion shows how this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6522 function works. The first point deals with a detail in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6523 documentation string, and the second point concerns the last line of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6524 the function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6525
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6526 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6527 In the documentation string, there is reference to an expression:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6528
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6529 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6530 \\[universal-argument]
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6531 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6532
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6533 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6534 A @samp{\\} is used before the first square bracket of this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6535 expression. This @samp{\\} tells the Lisp interpreter to substitute
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6536 whatever key is currently bound to the @samp{[@dots{}]}. In the case
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6537 of @code{universal-argument}, that is usually @kbd{C-u}, but it might
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6538 be different. (@xref{Documentation Tips, , Tips for Documentation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6539 Strings, elisp, The GNU Emacs Lisp Reference Manual}, for more
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6540 information.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6541
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6542 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6543 Finally, the last line of the @code{beginning-of-buffer} command says
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6544 to move point to the beginning of the next line if the command is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6545 invoked with an argument:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6546
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6547 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6548 (if arg (forward-line 1)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6549 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6550
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6551 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6552 This puts the cursor at the beginning of the first line after the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6553 appropriate tenths position in the buffer. This is a flourish that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6554 means that the cursor is always located @emph{at least} the requested
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6555 tenths of the way through the buffer, which is a nicety that is,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6556 perhaps, not necessary, but which, if it did not occur, would be sure
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6557 to draw complaints.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6558
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6559 On the other hand, it also means that if you specify the command with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6560 a @kbd{C-u}, but without a number, that is to say, if the `raw prefix
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6561 argument' is simply a cons cell, then the command puts you at the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6562 beginning of the second line @dots{} I don't know whether this is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6563 intended or whether no one has dealt with the code to avoid this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6564 happening.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6565
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6566 @node Second Buffer Related Review, optional Exercise, beginning-of-buffer, More Complex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6567 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6568 @section Review
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6569
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6570 Here is a brief summary of some of the topics covered in this chapter.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6571
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6572 @table @code
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6573 @item or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6574 Evaluate each argument in sequence, and return the value of the first
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6575 argument that is not @code{nil}; if none return a value that is not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6576 @code{nil}, return @code{nil}. In brief, return the first true value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6577 of the arguments; return a true value if one @emph{or} any of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6578 others are true.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6579
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6580 @item and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6581 Evaluate each argument in sequence, and if any are @code{nil}, return
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6582 @code{nil}; if none are @code{nil}, return the value of the last
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6583 argument. In brief, return a true value only if all the arguments are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6584 true; return a true value if one @emph{and} each of the others is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6585 true.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6586
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6587 @item &optional
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6588 A keyword used to indicate that an argument to a function definition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6589 is optional; this means that the function can be evaluated without the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6590 argument, if desired.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6591
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6592 @item prefix-numeric-value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6593 Convert the `raw prefix argument' produced by @code{(interactive
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6594 "P")} to a numeric value.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6595
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6596 @item forward-line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6597 Move point forward to the beginning of the next line, or if the argument
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6598 is greater than one, forward that many lines. If it can't move as far
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6599 forward as it is supposed to, @code{forward-line} goes forward as far as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6600 it can and then returns a count of the number of additional lines it was
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6601 supposed to move but couldn't.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6602
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6603 @item erase-buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6604 Delete the entire contents of the current buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6605
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6606 @item bufferp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6607 Return @code{t} if its argument is a buffer; otherwise return @code{nil}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6608 @end table
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6609
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6610 @node optional Exercise, , Second Buffer Related Review, More Complex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6611 @section @code{optional} Argument Exercise
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6612
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6613 Write an interactive function with an optional argument that tests
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6614 whether its argument, a number, is greater than or equal to, or else,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6615 less than the value of @code{fill-column}, and tells you which, in a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6616 message. However, if you do not pass an argument to the function, use
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6617 56 as a default value.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6618
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6619 @node Narrowing & Widening, car cdr & cons, More Complex, Top
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6620 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6621 @chapter Narrowing and Widening
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6622 @cindex Focusing attention (narrowing)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6623 @cindex Narrowing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6624 @cindex Widening
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6625
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6626 Narrowing is a feature of Emacs that makes it possible for you to focus
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6627 on a specific part of a buffer, and work without accidentally changing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6628 other parts. Narrowing is normally disabled since it can confuse
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6629 novices.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6630
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6631 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6632 * Narrowing advantages:: The advantages of narrowing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6633 * save-restriction:: The @code{save-restriction} special form.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6634 * what-line:: The number of the line that point is on.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6635 * narrow Exercise::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6636 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6637
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6638 @node Narrowing advantages, save-restriction, Narrowing & Widening, Narrowing & Widening
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6639 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6640 @unnumberedsec The Advantages of Narrowing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6641 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6642
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6643 With narrowing, the rest of a buffer is made invisible, as if it weren't
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6644 there. This is an advantage if, for example, you want to replace a word
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6645 in one part of a buffer but not in another: you narrow to the part you want
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6646 and the replacement is carried out only in that section, not in the rest
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6647 of the buffer. Searches will only work within a narrowed region, not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6648 outside of one, so if you are fixing a part of a document, you can keep
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6649 yourself from accidentally finding parts you do not need to fix by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6650 narrowing just to the region you want.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6651 (The key binding for @code{narrow-to-region} is @kbd{C-x n n}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6652
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6653 However, narrowing does make the rest of the buffer invisible, which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6654 can scare people who inadvertently invoke narrowing and think they
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6655 have deleted a part of their file. Moreover, the @code{undo} command
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6656 (which is usually bound to @kbd{C-x u}) does not turn off narrowing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6657 (nor should it), so people can become quite desperate if they do not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6658 know that they can return the rest of a buffer to visibility with the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6659 @code{widen} command.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6660 (The key binding for @code{widen} is @kbd{C-x n w}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6661
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6662 Narrowing is just as useful to the Lisp interpreter as to a human.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6663 Often, an Emacs Lisp function is designed to work on just part of a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6664 buffer; or conversely, an Emacs Lisp function needs to work on all of a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6665 buffer that has been narrowed. The @code{what-line} function, for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6666 example, removes the narrowing from a buffer, if it has any narrowing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6667 and when it has finished its job, restores the narrowing to what it was.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6668 On the other hand, the @code{count-lines} function, which is called by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6669 @code{what-line}, uses narrowing to restrict itself to just that portion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6670 of the buffer in which it is interested and then restores the previous
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6671 situation.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6672
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6673 @node save-restriction, what-line, Narrowing advantages, Narrowing & Widening
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6674 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6675 @section The @code{save-restriction} Special Form
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6676 @findex save-restriction
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6677
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6678 In Emacs Lisp, you can use the @code{save-restriction} special form to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6679 keep track of whatever narrowing is in effect, if any. When the Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6680 interpreter meets with @code{save-restriction}, it executes the code
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6681 in the body of the @code{save-restriction} expression, and then undoes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6682 any changes to narrowing that the code caused. If, for example, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6683 buffer is narrowed and the code that follows @code{save-restriction}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6684 gets rid of the narrowing, @code{save-restriction} returns the buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6685 to its narrowed region afterwards. In the @code{what-line} command,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6686 any narrowing the buffer may have is undone by the @code{widen}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6687 command that immediately follows the @code{save-restriction} command.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6688 Any original narrowing is restored just before the completion of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6689 function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6690
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6691 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6692 The template for a @code{save-restriction} expression is simple:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6693
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6694 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6695 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6696 (save-restriction
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6697 @var{body}@dots{} )
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6698 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6699 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6700
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6701 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6702 The body of the @code{save-restriction} is one or more expressions that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6703 will be evaluated in sequence by the Lisp interpreter.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6704
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6705 Finally, a point to note: when you use both @code{save-excursion} and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6706 @code{save-restriction}, one right after the other, you should use
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6707 @code{save-excursion} outermost. If you write them in reverse order,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6708 you may fail to record narrowing in the buffer to which Emacs switches
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6709 after calling @code{save-excursion}. Thus, when written together,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6710 @code{save-excursion} and @code{save-restriction} should be written
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6711 like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6712
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6713 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6714 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6715 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6716 (save-restriction
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6717 @var{body}@dots{}))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6718 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6719 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6720
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6721 In other circumstances, when not written together, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6722 @code{save-excursion} and @code{save-restriction} special forms must
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6723 be written in the order appropriate to the function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6724
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6725 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6726 For example,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6727
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6728 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6729 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6730 (save-restriction
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6731 (widen)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6732 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6733 @var{body}@dots{}))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6734 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6735 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6736
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6737 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6738 Emacs 22
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6739 /usr/local/src/emacs/lisp/simple.el
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6740
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6741 (defun what-line ()
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6742 "Print the current buffer line number and narrowed line number of point."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6743 (interactive)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6744 (let ((start (point-min))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6745 (n (line-number-at-pos)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6746 (if (= start 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6747 (message "Line %d" n)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6748 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6749 (save-restriction
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6750 (widen)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6751 (message "line %d (narrowed line %d)"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6752 (+ n (line-number-at-pos start) -1) n))))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6753
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6754 (defun line-number-at-pos (&optional pos)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6755 "Return (narrowed) buffer line number at position POS.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6756 If POS is nil, use current buffer location.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6757 Counting starts at (point-min), so the value refers
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6758 to the contents of the accessible portion of the buffer."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6759 (let ((opoint (or pos (point))) start)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6760 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6761 (goto-char (point-min))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6762 (setq start (point))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6763 (goto-char opoint)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6764 (forward-line 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6765 (1+ (count-lines start (point))))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6766
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6767 (defun count-lines (start end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6768 "Return number of lines between START and END.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6769 This is usually the number of newlines between them,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6770 but can be one more if START is not equal to END
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6771 and the greater of them is not at the start of a line."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6772 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6773 (save-restriction
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6774 (narrow-to-region start end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6775 (goto-char (point-min))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6776 (if (eq selective-display t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6777 (save-match-data
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6778 (let ((done 0))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6779 (while (re-search-forward "[\n\C-m]" nil t 40)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6780 (setq done (+ 40 done)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6781 (while (re-search-forward "[\n\C-m]" nil t 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6782 (setq done (+ 1 done)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6783 (goto-char (point-max))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6784 (if (and (/= start end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6785 (not (bolp)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6786 (1+ done)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6787 done)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6788 (- (buffer-size) (forward-line (buffer-size)))))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6789 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6790
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6791 @node what-line, narrow Exercise, save-restriction, Narrowing & Widening
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6792 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6793 @section @code{what-line}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6794 @findex what-line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6795 @cindex Widening, example of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6796
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6797 The @code{what-line} command tells you the number of the line in which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6798 the cursor is located. The function illustrates the use of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6799 @code{save-restriction} and @code{save-excursion} commands. Here is the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6800 original text of the function:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6801
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6802 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6803 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6804 (defun what-line ()
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6805 "Print the current line number (in the buffer) of point."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6806 (interactive)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6807 (save-restriction
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6808 (widen)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6809 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6810 (beginning-of-line)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6811 (message "Line %d"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6812 (1+ (count-lines 1 (point)))))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6813 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6814 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6815
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6816 (In recent versions of GNU Emacs, the @code{what-line} function has
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6817 been expanded to tell you your line number in a narrowed buffer as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6818 well as your line number in a widened buffer. The recent version is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6819 more complex than the version shown here. If you feel adventurous,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6820 you might want to look at it after figuring out how this version
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6821 works. You will probably need to use @kbd{C-h f}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6822 (@code{describe-function}). The newer version uses a conditional to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6823 determine whether the buffer has been narrowed.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6824
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6825 (Also, it uses @code{line-number-at-pos}, which among other simple
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6826 expressions, such as @code{(goto-char (point-min))}, moves point to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6827 the beginning of the current line with @code{(forward-line 0)} rather
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6828 than @code{beginning-of-line}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6829
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6830 The @code{what-line} function as shown here has a documentation line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6831 and is interactive, as you would expect. The next two lines use the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6832 functions @code{save-restriction} and @code{widen}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6833
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6834 The @code{save-restriction} special form notes whatever narrowing is in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6835 effect, if any, in the current buffer and restores that narrowing after
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6836 the code in the body of the @code{save-restriction} has been evaluated.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6837
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6838 The @code{save-restriction} special form is followed by @code{widen}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6839 This function undoes any narrowing the current buffer may have had
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6840 when @code{what-line} was called. (The narrowing that was there is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6841 the narrowing that @code{save-restriction} remembers.) This widening
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6842 makes it possible for the line counting commands to count from the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6843 beginning of the buffer. Otherwise, they would have been limited to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6844 counting within the accessible region. Any original narrowing is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6845 restored just before the completion of the function by the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6846 @code{save-restriction} special form.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6847
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6848 The call to @code{widen} is followed by @code{save-excursion}, which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6849 saves the location of the cursor (i.e., of point) and of the mark, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6850 restores them after the code in the body of the @code{save-excursion}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6851 uses the @code{beginning-of-line} function to move point.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6852
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6853 (Note that the @code{(widen)} expression comes between the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6854 @code{save-restriction} and @code{save-excursion} special forms. When
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6855 you write the two @code{save- @dots{}} expressions in sequence, write
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6856 @code{save-excursion} outermost.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6857
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6858 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6859 The last two lines of the @code{what-line} function are functions to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6860 count the number of lines in the buffer and then print the number in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6861 echo area.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6862
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6863 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6864 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6865 (message "Line %d"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6866 (1+ (count-lines 1 (point)))))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6867 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6868 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6869
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6870 The @code{message} function prints a one-line message at the bottom of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6871 the Emacs screen. The first argument is inside of quotation marks and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6872 is printed as a string of characters. However, it may contain a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6873 @samp{%d} expression to print a following argument. @samp{%d} prints
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6874 the argument as a decimal, so the message will say something such as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6875 @samp{Line 243}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6876
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6877 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6878 The number that is printed in place of the @samp{%d} is computed by the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6879 last line of the function:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6880
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6881 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6882 (1+ (count-lines 1 (point)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6883 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6884
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6885 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6886 GNU Emacs 22
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6887
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6888 (defun count-lines (start end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6889 "Return number of lines between START and END.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6890 This is usually the number of newlines between them,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6891 but can be one more if START is not equal to END
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6892 and the greater of them is not at the start of a line."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6893 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6894 (save-restriction
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6895 (narrow-to-region start end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6896 (goto-char (point-min))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6897 (if (eq selective-display t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6898 (save-match-data
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6899 (let ((done 0))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6900 (while (re-search-forward "[\n\C-m]" nil t 40)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6901 (setq done (+ 40 done)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6902 (while (re-search-forward "[\n\C-m]" nil t 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6903 (setq done (+ 1 done)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6904 (goto-char (point-max))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6905 (if (and (/= start end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6906 (not (bolp)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6907 (1+ done)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6908 done)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6909 (- (buffer-size) (forward-line (buffer-size)))))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6910 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6911
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6912 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6913 What this does is count the lines from the first position of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6914 buffer, indicated by the @code{1}, up to @code{(point)}, and then add
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6915 one to that number. (The @code{1+} function adds one to its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6916 argument.) We add one to it because line 2 has only one line before
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6917 it, and @code{count-lines} counts only the lines @emph{before} the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6918 current line.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6919
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6920 After @code{count-lines} has done its job, and the message has been
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6921 printed in the echo area, the @code{save-excursion} restores point and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6922 mark to their original positions; and @code{save-restriction} restores
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6923 the original narrowing, if any.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6924
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6925 @node narrow Exercise, , what-line, Narrowing & Widening
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6926 @section Exercise with Narrowing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6927
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6928 Write a function that will display the first 60 characters of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6929 current buffer, even if you have narrowed the buffer to its latter
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6930 half so that the first line is inaccessible. Restore point, mark, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6931 narrowing. For this exercise, you need to use a whole potpourri of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6932 functions, including @code{save-restriction}, @code{widen},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6933 @code{goto-char}, @code{point-min}, @code{message}, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6934 @code{buffer-substring}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6935
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6936 @cindex Properties, mention of @code{buffer-substring-no-properties}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6937 (@code{buffer-substring} is a previously unmentioned function you will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6938 have to investigate yourself; or perhaps you will have to use
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6939 @code{buffer-substring-no-properties} or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6940 @code{filter-buffer-substring} @dots{}, yet other functions. Text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6941 properties are a feature otherwise not discussed here. @xref{Text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6942 Properties, , Text Properties, elisp, The GNU Emacs Lisp Reference
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6943 Manual}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6944
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6945 Additionally, do you really need @code{goto-char} or @code{point-min}?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6946 Or can you write the function without them?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6947
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6948 @node car cdr & cons, Cutting & Storing Text, Narrowing & Widening, Top
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6949 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6950 @chapter @code{car}, @code{cdr}, @code{cons}: Fundamental Functions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6951 @findex car, @r{introduced}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6952 @findex cdr, @r{introduced}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6953
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6954 In Lisp, @code{car}, @code{cdr}, and @code{cons} are fundamental
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6955 functions. The @code{cons} function is used to construct lists, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6956 the @code{car} and @code{cdr} functions are used to take them apart.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6957
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6958 In the walk through of the @code{copy-region-as-kill} function, we
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6959 will see @code{cons} as well as two variants on @code{cdr},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6960 namely, @code{setcdr} and @code{nthcdr}. (@xref{copy-region-as-kill}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6961
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6962 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6963 * Strange Names:: An historical aside: why the strange names?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6964 * car & cdr:: Functions for extracting part of a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6965 * cons:: Constructing a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6966 * nthcdr:: Calling @code{cdr} repeatedly.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6967 * nth::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6968 * setcar:: Changing the first element of a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6969 * setcdr:: Changing the rest of a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6970 * cons Exercise::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6971 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6972
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6973 @node Strange Names, car & cdr, car cdr & cons, car cdr & cons
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6974 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6975 @unnumberedsec Strange Names
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6976 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6977
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6978 The name of the @code{cons} function is not unreasonable: it is an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6979 abbreviation of the word `construct'. The origins of the names for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6980 @code{car} and @code{cdr}, on the other hand, are esoteric: @code{car}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6981 is an acronym from the phrase `Contents of the Address part of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6982 Register'; and @code{cdr} (pronounced `could-er') is an acronym from
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6983 the phrase `Contents of the Decrement part of the Register'. These
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6984 phrases refer to specific pieces of hardware on the very early
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6985 computer on which the original Lisp was developed. Besides being
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6986 obsolete, the phrases have been completely irrelevant for more than 25
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6987 years to anyone thinking about Lisp. Nonetheless, although a few
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6988 brave scholars have begun to use more reasonable names for these
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6989 functions, the old terms are still in use. In particular, since the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6990 terms are used in the Emacs Lisp source code, we will use them in this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6991 introduction.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6992
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6993 @node car & cdr, cons, Strange Names, car cdr & cons
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6994 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6995 @section @code{car} and @code{cdr}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6996
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6997 The @sc{car} of a list is, quite simply, the first item in the list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6998 Thus the @sc{car} of the list @code{(rose violet daisy buttercup)} is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
6999 @code{rose}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7000
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7001 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7002 If you are reading this in Info in GNU Emacs, you can see this by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7003 evaluating the following:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7004
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7005 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7006 (car '(rose violet daisy buttercup))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7007 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7008
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7009 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7010 After evaluating the expression, @code{rose} will appear in the echo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7011 area.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7012
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7013 Clearly, a more reasonable name for the @code{car} function would be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7014 @code{first} and this is often suggested.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7015
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7016 @code{car} does not remove the first item from the list; it only reports
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7017 what it is. After @code{car} has been applied to a list, the list is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7018 still the same as it was. In the jargon, @code{car} is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7019 `non-destructive'. This feature turns out to be important.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7020
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7021 The @sc{cdr} of a list is the rest of the list, that is, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7022 @code{cdr} function returns the part of the list that follows the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7023 first item. Thus, while the @sc{car} of the list @code{'(rose violet
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7024 daisy buttercup)} is @code{rose}, the rest of the list, the value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7025 returned by the @code{cdr} function, is @code{(violet daisy
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7026 buttercup)}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7027
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7028 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7029 You can see this by evaluating the following in the usual way:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7030
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7031 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7032 (cdr '(rose violet daisy buttercup))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7033 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7034
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7035 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7036 When you evaluate this, @code{(violet daisy buttercup)} will appear in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7037 the echo area.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7038
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7039 Like @code{car}, @code{cdr} does not remove any elements from the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7040 list---it just returns a report of what the second and subsequent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7041 elements are.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7042
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7043 Incidentally, in the example, the list of flowers is quoted. If it were
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7044 not, the Lisp interpreter would try to evaluate the list by calling
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7045 @code{rose} as a function. In this example, we do not want to do that.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7046
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7047 Clearly, a more reasonable name for @code{cdr} would be @code{rest}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7048
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7049 (There is a lesson here: when you name new functions, consider very
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7050 carefully what you are doing, since you may be stuck with the names
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7051 for far longer than you expect. The reason this document perpetuates
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7052 these names is that the Emacs Lisp source code uses them, and if I did
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7053 not use them, you would have a hard time reading the code; but do,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7054 please, try to avoid using these terms yourself. The people who come
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7055 after you will be grateful to you.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7056
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7057 When @code{car} and @code{cdr} are applied to a list made up of symbols,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7058 such as the list @code{(pine fir oak maple)}, the element of the list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7059 returned by the function @code{car} is the symbol @code{pine} without
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7060 any parentheses around it. @code{pine} is the first element in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7061 list. However, the @sc{cdr} of the list is a list itself, @code{(fir
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7062 oak maple)}, as you can see by evaluating the following expressions in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7063 the usual way:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7064
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7065 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7066 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7067 (car '(pine fir oak maple))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7068
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7069 (cdr '(pine fir oak maple))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7070 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7071 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7072
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7073 On the other hand, in a list of lists, the first element is itself a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7074 list. @code{car} returns this first element as a list. For example,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7075 the following list contains three sub-lists, a list of carnivores, a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7076 list of herbivores and a list of sea mammals:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7077
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7078 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7079 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7080 (car '((lion tiger cheetah)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7081 (gazelle antelope zebra)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7082 (whale dolphin seal)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7083 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7084 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7085
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7086 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7087 In this example, the first element or @sc{car} of the list is the list of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7088 carnivores, @code{(lion tiger cheetah)}, and the rest of the list is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7089 @code{((gazelle antelope zebra) (whale dolphin seal))}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7090
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7091 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7092 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7093 (cdr '((lion tiger cheetah)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7094 (gazelle antelope zebra)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7095 (whale dolphin seal)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7096 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7097 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7098
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7099 It is worth saying again that @code{car} and @code{cdr} are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7100 non-destructive---that is, they do not modify or change lists to which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7101 they are applied. This is very important for how they are used.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7102
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7103 Also, in the first chapter, in the discussion about atoms, I said that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7104 in Lisp, ``certain kinds of atom, such as an array, can be separated
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7105 into parts; but the mechanism for doing this is different from the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7106 mechanism for splitting a list. As far as Lisp is concerned, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7107 atoms of a list are unsplittable.'' (@xref{Lisp Atoms}.) The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7108 @code{car} and @code{cdr} functions are used for splitting lists and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7109 are considered fundamental to Lisp. Since they cannot split or gain
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7110 access to the parts of an array, an array is considered an atom.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7111 Conversely, the other fundamental function, @code{cons}, can put
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7112 together or construct a list, but not an array. (Arrays are handled
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7113 by array-specific functions. @xref{Arrays, , Arrays, elisp, The GNU
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7114 Emacs Lisp Reference Manual}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7115
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7116 @node cons, nthcdr, car & cdr, car cdr & cons
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7117 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7118 @section @code{cons}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7119 @findex cons, @r{introduced}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7120
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7121 The @code{cons} function constructs lists; it is the inverse of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7122 @code{car} and @code{cdr}. For example, @code{cons} can be used to make
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7123 a four element list from the three element list, @code{(fir oak maple)}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7124
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7125 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7126 (cons 'pine '(fir oak maple))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7127 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7128
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7129 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7130 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7131 After evaluating this list, you will see
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7132
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7133 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7134 (pine fir oak maple)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7135 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7136
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7137 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7138 appear in the echo area. @code{cons} causes the creation of a new
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7139 list in which the element is followed by the elements of the original
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7140 list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7141
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7142 We often say that `@code{cons} puts a new element at the beginning of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7143 a list; it attaches or pushes elements onto the list', but this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7144 phrasing can be misleading, since @code{cons} does not change an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7145 existing list, but creates a new one.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7146
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7147 Like @code{car} and @code{cdr}, @code{cons} is non-destructive.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7148
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7149 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7150 * Build a list::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7151 * length:: How to find the length of a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7152 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7153
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7154 @node Build a list, length, cons, cons
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7155 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7156 @unnumberedsubsec Build a list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7157 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7158
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7159 @code{cons} must have a list to attach to.@footnote{Actually, you can
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7160 @code{cons} an element to an atom to produce a dotted pair. Dotted
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7161 pairs are not discussed here; see @ref{Dotted Pair Notation, , Dotted
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7162 Pair Notation, elisp, The GNU Emacs Lisp Reference Manual}.} You
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7163 cannot start from absolutely nothing. If you are building a list, you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7164 need to provide at least an empty list at the beginning. Here is a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7165 series of @code{cons} expressions that build up a list of flowers. If
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7166 you are reading this in Info in GNU Emacs, you can evaluate each of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7167 the expressions in the usual way; the value is printed in this text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7168 after @samp{@result{}}, which you may read as `evaluates to'.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7169
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7170 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7171 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7172 (cons 'buttercup ())
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7173 @result{} (buttercup)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7174 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7175
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7176 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7177 (cons 'daisy '(buttercup))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7178 @result{} (daisy buttercup)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7179 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7180
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7181 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7182 (cons 'violet '(daisy buttercup))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7183 @result{} (violet daisy buttercup)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7184 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7185
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7186 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7187 (cons 'rose '(violet daisy buttercup))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7188 @result{} (rose violet daisy buttercup)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7189 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7190 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7191
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7192 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7193 In the first example, the empty list is shown as @code{()} and a list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7194 made up of @code{buttercup} followed by the empty list is constructed.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7195 As you can see, the empty list is not shown in the list that was
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7196 constructed. All that you see is @code{(buttercup)}. The empty list is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7197 not counted as an element of a list because there is nothing in an empty
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7198 list. Generally speaking, an empty list is invisible.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7199
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7200 The second example, @code{(cons 'daisy '(buttercup))} constructs a new,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7201 two element list by putting @code{daisy} in front of @code{buttercup};
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7202 and the third example constructs a three element list by putting
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7203 @code{violet} in front of @code{daisy} and @code{buttercup}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7204
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7205 @node length, , Build a list, cons
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7206 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7207 @subsection Find the Length of a List: @code{length}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7208 @findex length
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7209
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7210 You can find out how many elements there are in a list by using the Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7211 function @code{length}, as in the following examples:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7212
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7213 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7214 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7215 (length '(buttercup))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7216 @result{} 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7217 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7218
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7219 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7220 (length '(daisy buttercup))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7221 @result{} 2
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7222 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7223
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7224 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7225 (length (cons 'violet '(daisy buttercup)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7226 @result{} 3
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7227 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7228 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7229
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7230 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7231 In the third example, the @code{cons} function is used to construct a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7232 three element list which is then passed to the @code{length} function as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7233 its argument.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7234
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7235 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7236 We can also use @code{length} to count the number of elements in an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7237 empty list:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7238
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7239 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7240 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7241 (length ())
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7242 @result{} 0
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7243 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7244 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7245
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7246 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7247 As you would expect, the number of elements in an empty list is zero.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7248
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7249 An interesting experiment is to find out what happens if you try to find
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7250 the length of no list at all; that is, if you try to call @code{length}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7251 without giving it an argument, not even an empty list:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7252
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7253 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7254 (length )
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7255 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7256
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7257 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7258 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7259 What you see, if you evaluate this, is the error message
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7260
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7261 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7262 Lisp error: (wrong-number-of-arguments length 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7263 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7264
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7265 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7266 This means that the function receives the wrong number of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7267 arguments, zero, when it expects some other number of arguments. In
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7268 this case, one argument is expected, the argument being a list whose
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7269 length the function is measuring. (Note that @emph{one} list is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7270 @emph{one} argument, even if the list has many elements inside it.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7271
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7272 The part of the error message that says @samp{length} is the name of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7273 the function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7274
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7275 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7276 @code{length} is still a subroutine, but you need C-h f to discover that.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7277
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7278 In an earlier version:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7279 This is written with a special notation, @samp{#<subr},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7280 that indicates that the function @code{length} is one of the primitive
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7281 functions written in C rather than in Emacs Lisp. (@samp{subr} is an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7282 abbreviation for `subroutine'.) @xref{What Is a Function, , What Is a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7283 Function?, elisp , The GNU Emacs Lisp Reference Manual}, for more
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7284 about subroutines.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7285 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7286
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7287 @node nthcdr, nth, cons, car cdr & cons
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7288 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7289 @section @code{nthcdr}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7290 @findex nthcdr
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7291
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7292 The @code{nthcdr} function is associated with the @code{cdr} function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7293 What it does is take the @sc{cdr} of a list repeatedly.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7294
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7295 If you take the @sc{cdr} of the list @code{(pine fir
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7296 oak maple)}, you will be returned the list @code{(fir oak maple)}. If you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7297 repeat this on what was returned, you will be returned the list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7298 @code{(oak maple)}. (Of course, repeated @sc{cdr}ing on the original
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7299 list will just give you the original @sc{cdr} since the function does
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7300 not change the list. You need to evaluate the @sc{cdr} of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7301 @sc{cdr} and so on.) If you continue this, eventually you will be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7302 returned an empty list, which in this case, instead of being shown as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7303 @code{()} is shown as @code{nil}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7304
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7305 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7306 For review, here is a series of repeated @sc{cdr}s, the text following
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7307 the @samp{@result{}} shows what is returned.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7308
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7309 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7310 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7311 (cdr '(pine fir oak maple))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7312 @result{}(fir oak maple)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7313 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7314
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7315 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7316 (cdr '(fir oak maple))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7317 @result{} (oak maple)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7318 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7319
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7320 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7321 (cdr '(oak maple))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7322 @result{}(maple)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7323 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7324
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7325 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7326 (cdr '(maple))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7327 @result{} nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7328 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7329
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7330 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7331 (cdr 'nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7332 @result{} nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7333 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7334
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7335 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7336 (cdr ())
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7337 @result{} nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7338 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7339 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7340
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7341 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7342 You can also do several @sc{cdr}s without printing the values in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7343 between, like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7344
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7345 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7346 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7347 (cdr (cdr '(pine fir oak maple)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7348 @result{} (oak maple)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7349 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7350 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7351
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7352 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7353 In this example, the Lisp interpreter evaluates the innermost list first.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7354 The innermost list is quoted, so it just passes the list as it is to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7355 innermost @code{cdr}. This @code{cdr} passes a list made up of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7356 second and subsequent elements of the list to the outermost @code{cdr},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7357 which produces a list composed of the third and subsequent elements of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7358 the original list. In this example, the @code{cdr} function is repeated
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7359 and returns a list that consists of the original list without its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7360 first two elements.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7361
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7362 The @code{nthcdr} function does the same as repeating the call to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7363 @code{cdr}. In the following example, the argument 2 is passed to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7364 function @code{nthcdr}, along with the list, and the value returned is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7365 the list without its first two items, which is exactly the same
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7366 as repeating @code{cdr} twice on the list:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7367
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7368 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7369 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7370 (nthcdr 2 '(pine fir oak maple))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7371 @result{} (oak maple)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7372 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7373 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7374
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7375 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7376 Using the original four element list, we can see what happens when
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7377 various numeric arguments are passed to @code{nthcdr}, including 0, 1,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7378 and 5:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7379
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7380 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7381 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7382 ;; @r{Leave the list as it was.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7383 (nthcdr 0 '(pine fir oak maple))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7384 @result{} (pine fir oak maple)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7385 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7386
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7387 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7388 ;; @r{Return a copy without the first element.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7389 (nthcdr 1 '(pine fir oak maple))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7390 @result{} (fir oak maple)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7391 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7392
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7393 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7394 ;; @r{Return a copy of the list without three elements.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7395 (nthcdr 3 '(pine fir oak maple))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7396 @result{} (maple)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7397 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7398
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7399 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7400 ;; @r{Return a copy lacking all four elements.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7401 (nthcdr 4 '(pine fir oak maple))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7402 @result{} nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7403 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7404
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7405 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7406 ;; @r{Return a copy lacking all elements.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7407 (nthcdr 5 '(pine fir oak maple))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7408 @result{} nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7409 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7410 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7411
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7412 @node nth, setcar, nthcdr, car cdr & cons
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7413 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7414 @section @code{nth}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7415 @findex nth
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7416
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7417 The @code{nthcdr} function takes the @sc{cdr} of a list repeatedly.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7418 The @code{nth} function takes the @sc{car} of the result returned by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7419 @code{nthcdr}. It returns the Nth element of the list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7420
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7421 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7422 Thus, if it were not defined in C for speed, the definition of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7423 @code{nth} would be:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7424
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7425 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7426 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7427 (defun nth (n list)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7428 "Returns the Nth element of LIST.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7429 N counts from zero. If LIST is not that long, nil is returned."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7430 (car (nthcdr n list)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7431 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7432 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7433
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7434 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7435 (Originally, @code{nth} was defined in Emacs Lisp in @file{subr.el},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7436 but its definition was redone in C in the 1980s.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7437
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7438 The @code{nth} function returns a single element of a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7439 This can be very convenient.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7440
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7441 Note that the elements are numbered from zero, not one. That is to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7442 say, the first element of a list, its @sc{car} is the zeroth element.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7443 This is called `zero-based' counting and often bothers people who
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7444 are accustomed to the first element in a list being number one, which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7445 is `one-based'.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7446
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7447 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7448 For example:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7449
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7450 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7451 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7452 (nth 0 '("one" "two" "three"))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7453 @result{} "one"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7454
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7455 (nth 1 '("one" "two" "three"))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7456 @result{} "two"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7457 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7458 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7459
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7460 It is worth mentioning that @code{nth}, like @code{nthcdr} and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7461 @code{cdr}, does not change the original list---the function is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7462 non-destructive. This is in sharp contrast to the @code{setcar} and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7463 @code{setcdr} functions.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7464
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7465 @node setcar, setcdr, nth, car cdr & cons
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7466 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7467 @section @code{setcar}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7468 @findex setcar
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7469
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7470 As you might guess from their names, the @code{setcar} and @code{setcdr}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7471 functions set the @sc{car} or the @sc{cdr} of a list to a new value.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7472 They actually change the original list, unlike @code{car} and @code{cdr}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7473 which leave the original list as it was. One way to find out how this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7474 works is to experiment. We will start with the @code{setcar} function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7475
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7476 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7477 First, we can make a list and then set the value of a variable to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7478 list, using the @code{setq} function. Here is a list of animals:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7479
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7480 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7481 (setq animals '(antelope giraffe lion tiger))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7482 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7483
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7484 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7485 If you are reading this in Info inside of GNU Emacs, you can evaluate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7486 this expression in the usual fashion, by positioning the cursor after
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7487 the expression and typing @kbd{C-x C-e}. (I'm doing this right here
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7488 as I write this. This is one of the advantages of having the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7489 interpreter built into the computing environment. Incidentally, when
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7490 there is nothing on the line after the final parentheses, such as a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7491 comment, point can be on the next line. Thus, if your cursor is in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7492 the first column of the next line, you do not need to move it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7493 Indeed, Emacs permits any amount of white space after the final
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7494 parenthesis.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7495
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7496 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7497 When we evaluate the variable @code{animals}, we see that it is bound to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7498 the list @code{(antelope giraffe lion tiger)}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7499
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7500 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7501 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7502 animals
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7503 @result{} (antelope giraffe lion tiger)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7504 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7505 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7506
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7507 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7508 Put another way, the variable @code{animals} points to the list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7509 @code{(antelope giraffe lion tiger)}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7510
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7511 Next, evaluate the function @code{setcar} while passing it two
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7512 arguments, the variable @code{animals} and the quoted symbol
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7513 @code{hippopotamus}; this is done by writing the three element list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7514 @code{(setcar animals 'hippopotamus)} and then evaluating it in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7515 usual fashion:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7516
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7517 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7518 (setcar animals 'hippopotamus)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7519 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7520
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7521 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7522 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7523 After evaluating this expression, evaluate the variable @code{animals}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7524 again. You will see that the list of animals has changed:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7525
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7526 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7527 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7528 animals
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7529 @result{} (hippopotamus giraffe lion tiger)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7530 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7531 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7532
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7533 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7534 The first element on the list, @code{antelope} is replaced by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7535 @code{hippopotamus}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7536
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7537 So we can see that @code{setcar} did not add a new element to the list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7538 as @code{cons} would have; it replaced @code{antelope} with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7539 @code{hippopotamus}; it @emph{changed} the list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7540
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7541 @node setcdr, cons Exercise, setcar, car cdr & cons
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7542 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7543 @section @code{setcdr}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7544 @findex setcdr
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7545
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7546 The @code{setcdr} function is similar to the @code{setcar} function,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7547 except that the function replaces the second and subsequent elements of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7548 a list rather than the first element.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7549
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7550 (To see how to change the last element of a list, look ahead to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7551 @ref{kill-new function, , The @code{kill-new} function}, which uses
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7552 the @code{nthcdr} and @code{setcdr} functions.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7553
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7554 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7555 To see how this works, set the value of the variable to a list of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7556 domesticated animals by evaluating the following expression:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7557
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7558 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7559 (setq domesticated-animals '(horse cow sheep goat))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7560 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7561
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7562 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7563 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7564 If you now evaluate the list, you will be returned the list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7565 @code{(horse cow sheep goat)}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7566
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7567 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7568 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7569 domesticated-animals
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7570 @result{} (horse cow sheep goat)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7571 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7572 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7573
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7574 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7575 Next, evaluate @code{setcdr} with two arguments, the name of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7576 variable which has a list as its value, and the list to which the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7577 @sc{cdr} of the first list will be set;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7578
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7579 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7580 (setcdr domesticated-animals '(cat dog))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7581 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7582
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7583 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7584 If you evaluate this expression, the list @code{(cat dog)} will appear
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7585 in the echo area. This is the value returned by the function. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7586 result we are interested in is the ``side effect'', which we can see by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7587 evaluating the variable @code{domesticated-animals}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7588
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7589 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7590 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7591 domesticated-animals
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7592 @result{} (horse cat dog)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7593 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7594 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7595
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7596 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7597 Indeed, the list is changed from @code{(horse cow sheep goat)} to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7598 @code{(horse cat dog)}. The @sc{cdr} of the list is changed from
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7599 @code{(cow sheep goat)} to @code{(cat dog)}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7600
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7601 @node cons Exercise, , setcdr, car cdr & cons
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7602 @section Exercise
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7603
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7604 Construct a list of four birds by evaluating several expressions with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7605 @code{cons}. Find out what happens when you @code{cons} a list onto
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7606 itself. Replace the first element of the list of four birds with a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7607 fish. Replace the rest of that list with a list of other fish.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7608
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7609 @node Cutting & Storing Text, List Implementation, car cdr & cons, Top
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7610 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7611 @chapter Cutting and Storing Text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7612 @cindex Cutting and storing text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7613 @cindex Storing and cutting text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7614 @cindex Killing text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7615 @cindex Clipping text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7616 @cindex Erasing text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7617 @cindex Deleting text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7618
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7619 Whenever you cut or clip text out of a buffer with a `kill' command in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7620 GNU Emacs, it is stored in a list and you can bring it back with a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7621 `yank' command.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7622
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7623 (The use of the word `kill' in Emacs for processes which specifically
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7624 @emph{do not} destroy the values of the entities is an unfortunate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7625 historical accident. A much more appropriate word would be `clip' since
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7626 that is what the kill commands do; they clip text out of a buffer and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7627 put it into storage from which it can be brought back. I have often
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7628 been tempted to replace globally all occurrences of `kill' in the Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7629 sources with `clip' and all occurrences of `killed' with `clipped'.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7630
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7631 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7632 * Storing Text:: Text is stored in a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7633 * zap-to-char:: Cutting out text up to a character.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7634 * kill-region:: Cutting text out of a region.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7635 * copy-region-as-kill:: A definition for copying text.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7636 * Digression into C:: Minor note on C programming language macros.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7637 * defvar:: How to give a variable an initial value.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7638 * cons & search-fwd Review::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7639 * search Exercises::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7640 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7641
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7642 @node Storing Text, zap-to-char, Cutting & Storing Text, Cutting & Storing Text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7643 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7644 @unnumberedsec Storing Text in a List
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7645 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7646
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7647 When text is cut out of a buffer, it is stored on a list. Successive
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7648 pieces of text are stored on the list successively, so the list might
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7649 look like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7650
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7651 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7652 ("a piece of text" "previous piece")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7653 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7654
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7655 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7656 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7657 The function @code{cons} can be used to create a new list from a piece
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7658 of text (an `atom', to use the jargon) and an existing list, like
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7659 this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7660
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7661 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7662 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7663 (cons "another piece"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7664 '("a piece of text" "previous piece"))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7665 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7666 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7667
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7668 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7669 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7670 If you evaluate this expression, a list of three elements will appear in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7671 the echo area:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7672
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7673 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7674 ("another piece" "a piece of text" "previous piece")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7675 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7676
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7677 With the @code{car} and @code{nthcdr} functions, you can retrieve
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7678 whichever piece of text you want. For example, in the following code,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7679 @code{nthcdr 1 @dots{}} returns the list with the first item removed;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7680 and the @code{car} returns the first element of that remainder---the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7681 second element of the original list:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7682
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7683 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7684 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7685 (car (nthcdr 1 '("another piece"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7686 "a piece of text"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7687 "previous piece")))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7688 @result{} "a piece of text"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7689 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7690 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7691
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7692 The actual functions in Emacs are more complex than this, of course.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7693 The code for cutting and retrieving text has to be written so that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7694 Emacs can figure out which element in the list you want---the first,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7695 second, third, or whatever. In addition, when you get to the end of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7696 the list, Emacs should give you the first element of the list, rather
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7697 than nothing at all.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7698
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7699 The list that holds the pieces of text is called the @dfn{kill ring}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7700 This chapter leads up to a description of the kill ring and how it is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7701 used by first tracing how the @code{zap-to-char} function works. This
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7702 function uses (or `calls') a function that invokes a function that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7703 manipulates the kill ring. Thus, before reaching the mountains, we
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7704 climb the foothills.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7705
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7706 A subsequent chapter describes how text that is cut from the buffer is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7707 retrieved. @xref{Yanking, , Yanking Text Back}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7708
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7709 @node zap-to-char, kill-region, Storing Text, Cutting & Storing Text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7710 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7711 @section @code{zap-to-char}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7712 @findex zap-to-char
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7713
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7714 The @code{zap-to-char} function changed little between GNU Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7715 version 19 and GNU Emacs version 22. However, @code{zap-to-char}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7716 calls another function, @code{kill-region}, which enjoyed a major
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7717 rewrite.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7718
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7719 The @code{kill-region} function in Emacs 19 is complex, but does not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7720 use code that is important at this time. We will skip it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7721
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7722 The @code{kill-region} function in Emacs 22 is easier to read than the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7723 same function in Emacs 19 and introduces a very important concept,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7724 that of error handling. We will walk through the function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7725
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7726 But first, let us look at the interactive @code{zap-to-char} function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7727
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7728 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7729 * Complete zap-to-char:: The complete implementation.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7730 * zap-to-char interactive:: A three part interactive expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7731 * zap-to-char body:: A short overview.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7732 * search-forward:: How to search for a string.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7733 * progn:: The @code{progn} special form.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7734 * Summing up zap-to-char:: Using @code{point} and @code{search-forward}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7735 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7736
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7737 @node Complete zap-to-char, zap-to-char interactive, zap-to-char, zap-to-char
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7738 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7739 @unnumberedsubsec The Complete @code{zap-to-char} Implementation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7740 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7741
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7742 The @code{zap-to-char} function removes the text in the region between
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7743 the location of the cursor (i.e., of point) up to and including the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7744 next occurrence of a specified character. The text that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7745 @code{zap-to-char} removes is put in the kill ring; and it can be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7746 retrieved from the kill ring by typing @kbd{C-y} (@code{yank}). If
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7747 the command is given an argument, it removes text through that number
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7748 of occurrences. Thus, if the cursor were at the beginning of this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7749 sentence and the character were @samp{s}, @samp{Thus} would be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7750 removed. If the argument were two, @samp{Thus, if the curs} would be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7751 removed, up to and including the @samp{s} in @samp{cursor}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7752
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7753 If the specified character is not found, @code{zap-to-char} will say
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7754 ``Search failed'', tell you the character you typed, and not remove
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7755 any text.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7756
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7757 In order to determine how much text to remove, @code{zap-to-char} uses
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7758 a search function. Searches are used extensively in code that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7759 manipulates text, and we will focus attention on them as well as on the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7760 deletion command.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7761
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7762 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7763 @c GNU Emacs version 19
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7764 (defun zap-to-char (arg char) ; version 19 implementation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7765 "Kill up to and including ARG'th occurrence of CHAR.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7766 Goes backward if ARG is negative; error if CHAR not found."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7767 (interactive "*p\ncZap to char: ")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7768 (kill-region (point)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7769 (progn
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7770 (search-forward
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7771 (char-to-string char) nil nil arg)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7772 (point))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7773 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7774
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7775 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7776 Here is the complete text of the version 22 implementation of the function:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7777
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7778 @c GNU Emacs 22
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7779 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7780 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7781 (defun zap-to-char (arg char)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7782 "Kill up to and including ARG'th occurrence of CHAR.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7783 Case is ignored if `case-fold-search' is non-nil in the current buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7784 Goes backward if ARG is negative; error if CHAR not found."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7785 (interactive "p\ncZap to char: ")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7786 (if (char-table-p translation-table-for-input)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7787 (setq char (or (aref translation-table-for-input char) char)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7788 (kill-region (point) (progn
98525
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
7789 (search-forward (char-to-string char)
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
7790 nil nil arg)
83955
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7791 (point))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7792 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7793 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7794
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7795 The documentation is thorough. You do need to know the jargon meaning
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7796 of the word `kill'.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7797
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7798 @node zap-to-char interactive, zap-to-char body, Complete zap-to-char, zap-to-char
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7799 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7800 @subsection The @code{interactive} Expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7801
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7802 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7803 The interactive expression in the @code{zap-to-char} command looks like
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7804 this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7805
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7806 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7807 (interactive "p\ncZap to char: ")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7808 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7809
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7810 The part within quotation marks, @code{"p\ncZap to char:@: "}, specifies
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7811 two different things. First, and most simply, is the @samp{p}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7812 This part is separated from the next part by a newline, @samp{\n}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7813 The @samp{p} means that the first argument to the function will be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7814 passed the value of a `processed prefix'. The prefix argument is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7815 passed by typing @kbd{C-u} and a number, or @kbd{M-} and a number. If
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7816 the function is called interactively without a prefix, 1 is passed to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7817 this argument.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7818
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7819 The second part of @code{"p\ncZap to char:@: "} is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7820 @samp{cZap to char:@: }. In this part, the lower case @samp{c}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7821 indicates that @code{interactive} expects a prompt and that the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7822 argument will be a character. The prompt follows the @samp{c} and is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7823 the string @samp{Zap to char:@: } (with a space after the colon to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7824 make it look good).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7825
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7826 What all this does is prepare the arguments to @code{zap-to-char} so they
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7827 are of the right type, and give the user a prompt.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7828
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7829 In a read-only buffer, the @code{zap-to-char} function copies the text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7830 to the kill ring, but does not remove it. The echo area displays a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7831 message saying that the buffer is read-only. Also, the terminal may
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7832 beep or blink at you.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7833
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7834 @node zap-to-char body, search-forward, zap-to-char interactive, zap-to-char
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7835 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7836 @subsection The Body of @code{zap-to-char}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7837
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7838 The body of the @code{zap-to-char} function contains the code that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7839 kills (that is, removes) the text in the region from the current
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7840 position of the cursor up to and including the specified character.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7841
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7842 The first part of the code looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7843
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7844 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7845 (if (char-table-p translation-table-for-input)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7846 (setq char (or (aref translation-table-for-input char) char)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7847 (kill-region (point) (progn
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7848 (search-forward (char-to-string char) nil nil arg)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7849 (point)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7850 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7851
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7852 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7853 @code{char-table-p} is an hitherto unseen function. It determines
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7854 whether its argument is a character table. When it is, it sets the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7855 character passed to @code{zap-to-char} to one of them, if that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7856 character exists, or to the character itself. (This becomes important
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7857 for certain characters in non-European languages. The @code{aref}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7858 function extracts an element from an array. It is an array-specific
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7859 function that is not described in this document. @xref{Arrays, ,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7860 Arrays, elisp, The GNU Emacs Lisp Reference Manual}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7861
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7862 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7863 @code{(point)} is the current position of the cursor.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7864
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7865 The next part of the code is an expression using @code{progn}. The body
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7866 of the @code{progn} consists of calls to @code{search-forward} and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7867 @code{point}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7868
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7869 It is easier to understand how @code{progn} works after learning about
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7870 @code{search-forward}, so we will look at @code{search-forward} and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7871 then at @code{progn}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7872
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7873 @node search-forward, progn, zap-to-char body, zap-to-char
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7874 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7875 @subsection The @code{search-forward} Function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7876 @findex search-forward
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7877
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7878 The @code{search-forward} function is used to locate the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7879 zapped-for-character in @code{zap-to-char}. If the search is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7880 successful, @code{search-forward} leaves point immediately after the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7881 last character in the target string. (In @code{zap-to-char}, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7882 target string is just one character long. @code{zap-to-char} uses the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7883 function @code{char-to-string} to ensure that the computer treats that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7884 character as a string.) If the search is backwards,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7885 @code{search-forward} leaves point just before the first character in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7886 the target. Also, @code{search-forward} returns @code{t} for true.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7887 (Moving point is therefore a `side effect'.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7888
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7889 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7890 In @code{zap-to-char}, the @code{search-forward} function looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7891
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7892 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7893 (search-forward (char-to-string char) nil nil arg)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7894 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7895
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7896 The @code{search-forward} function takes four arguments:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7897
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7898 @enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7899 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7900 The first argument is the target, what is searched for. This must be a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7901 string, such as @samp{"z"}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7902
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7903 As it happens, the argument passed to @code{zap-to-char} is a single
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7904 character. Because of the way computers are built, the Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7905 interpreter may treat a single character as being different from a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7906 string of characters. Inside the computer, a single character has a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7907 different electronic format than a string of one character. (A single
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7908 character can often be recorded in the computer using exactly one
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7909 byte; but a string may be longer, and the computer needs to be ready
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7910 for this.) Since the @code{search-forward} function searches for a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7911 string, the character that the @code{zap-to-char} function receives as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7912 its argument must be converted inside the computer from one format to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7913 the other; otherwise the @code{search-forward} function will fail.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7914 The @code{char-to-string} function is used to make this conversion.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7915
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7916 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7917 The second argument bounds the search; it is specified as a position in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7918 the buffer. In this case, the search can go to the end of the buffer,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7919 so no bound is set and the second argument is @code{nil}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7920
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7921 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7922 The third argument tells the function what it should do if the search
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7923 fails---it can signal an error (and print a message) or it can return
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7924 @code{nil}. A @code{nil} as the third argument causes the function to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7925 signal an error when the search fails.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7926
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7927 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7928 The fourth argument to @code{search-forward} is the repeat count---how
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7929 many occurrences of the string to look for. This argument is optional
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7930 and if the function is called without a repeat count, this argument is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7931 passed the value 1. If this argument is negative, the search goes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7932 backwards.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7933 @end enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7934
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7935 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7936 In template form, a @code{search-forward} expression looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7937
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7938 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7939 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7940 (search-forward "@var{target-string}"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7941 @var{limit-of-search}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7942 @var{what-to-do-if-search-fails}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7943 @var{repeat-count})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7944 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7945 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7946
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7947 We will look at @code{progn} next.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7948
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7949 @node progn, Summing up zap-to-char, search-forward, zap-to-char
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7950 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7951 @subsection The @code{progn} Special Form
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7952 @findex progn
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7953
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7954 @code{progn} is a special form that causes each of its arguments to be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7955 evaluated in sequence and then returns the value of the last one. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7956 preceding expressions are evaluated only for the side effects they
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7957 perform. The values produced by them are discarded.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7958
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7959 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7960 The template for a @code{progn} expression is very simple:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7961
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7962 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7963 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7964 (progn
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7965 @var{body}@dots{})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7966 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7967 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7968
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7969 In @code{zap-to-char}, the @code{progn} expression has to do two things:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7970 put point in exactly the right position; and return the location of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7971 point so that @code{kill-region} will know how far to kill to.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7972
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7973 The first argument to the @code{progn} is @code{search-forward}. When
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7974 @code{search-forward} finds the string, the function leaves point
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7975 immediately after the last character in the target string. (In this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7976 case the target string is just one character long.) If the search is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7977 backwards, @code{search-forward} leaves point just before the first
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7978 character in the target. The movement of point is a side effect.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7979
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7980 The second and last argument to @code{progn} is the expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7981 @code{(point)}. This expression returns the value of point, which in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7982 this case will be the location to which it has been moved by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7983 @code{search-forward}. (In the source, a line that tells the function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7984 to go to the previous character, if it is going forward, was commented
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7985 out in 1999; I don't remember whether that feature or mis-feature was
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7986 ever a part of the distributed source.) The value of @code{point} is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7987 returned by the @code{progn} expression and is passed to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7988 @code{kill-region} as @code{kill-region}'s second argument.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7989
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7990 @node Summing up zap-to-char, , progn, zap-to-char
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7991 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7992 @subsection Summing up @code{zap-to-char}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7993
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7994 Now that we have seen how @code{search-forward} and @code{progn} work,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7995 we can see how the @code{zap-to-char} function works as a whole.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7996
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7997 The first argument to @code{kill-region} is the position of the cursor
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7998 when the @code{zap-to-char} command is given---the value of point at
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7999 that time. Within the @code{progn}, the search function then moves
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8000 point to just after the zapped-to-character and @code{point} returns the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8001 value of this location. The @code{kill-region} function puts together
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8002 these two values of point, the first one as the beginning of the region
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8003 and the second one as the end of the region, and removes the region.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8004
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8005 The @code{progn} special form is necessary because the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8006 @code{kill-region} command takes two arguments; and it would fail if
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8007 @code{search-forward} and @code{point} expressions were written in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8008 sequence as two additional arguments. The @code{progn} expression is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8009 a single argument to @code{kill-region} and returns the one value that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8010 @code{kill-region} needs for its second argument.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8011
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8012 @node kill-region, copy-region-as-kill, zap-to-char, Cutting & Storing Text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8013 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8014 @section @code{kill-region}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8015 @findex kill-region
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8016
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8017 The @code{zap-to-char} function uses the @code{kill-region} function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8018 This function clips text from a region and copies that text to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8019 the kill ring, from which it may be retrieved.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8020
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8021 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8022 GNU Emacs 22:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8023
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8024 (defun kill-region (beg end &optional yank-handler)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8025 "Kill (\"cut\") text between point and mark.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8026 This deletes the text from the buffer and saves it in the kill ring.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8027 The command \\[yank] can retrieve it from there.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8028 \(If you want to kill and then yank immediately, use \\[kill-ring-save].)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8029
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8030 If you want to append the killed region to the last killed text,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8031 use \\[append-next-kill] before \\[kill-region].
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8032
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8033 If the buffer is read-only, Emacs will beep and refrain from deleting
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8034 the text, but put the text in the kill ring anyway. This means that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8035 you can use the killing commands to copy text from a read-only buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8036
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8037 This is the primitive for programs to kill text (as opposed to deleting it).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8038 Supply two arguments, character positions indicating the stretch of text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8039 to be killed.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8040 Any command that calls this function is a \"kill command\".
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8041 If the previous command was also a kill command,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8042 the text killed this time appends to the text killed last time
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8043 to make one entry in the kill ring.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8044
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8045 In Lisp code, optional third arg YANK-HANDLER, if non-nil,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8046 specifies the yank-handler text property to be set on the killed
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8047 text. See `insert-for-yank'."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8048 ;; Pass point first, then mark, because the order matters
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8049 ;; when calling kill-append.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8050 (interactive (list (point) (mark)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8051 (unless (and beg end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8052 (error "The mark is not set now, so there is no region"))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8053 (condition-case nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8054 (let ((string (filter-buffer-substring beg end t)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8055 (when string ;STRING is nil if BEG = END
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8056 ;; Add that string to the kill ring, one way or another.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8057 (if (eq last-command 'kill-region)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8058 (kill-append string (< end beg) yank-handler)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8059 (kill-new string nil yank-handler)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8060 (when (or string (eq last-command 'kill-region))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8061 (setq this-command 'kill-region))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8062 nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8063 ((buffer-read-only text-read-only)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8064 ;; The code above failed because the buffer, or some of the characters
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8065 ;; in the region, are read-only.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8066 ;; We should beep, in case the user just isn't aware of this.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8067 ;; However, there's no harm in putting
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8068 ;; the region's text in the kill ring, anyway.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8069 (copy-region-as-kill beg end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8070 ;; Set this-command now, so it will be set even if we get an error.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8071 (setq this-command 'kill-region)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8072 ;; This should barf, if appropriate, and give us the correct error.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8073 (if kill-read-only-ok
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8074 (progn (message "Read only text copied to kill ring") nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8075 ;; Signal an error if the buffer is read-only.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8076 (barf-if-buffer-read-only)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8077 ;; If the buffer isn't read-only, the text is.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8078 (signal 'text-read-only (list (current-buffer)))))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8079 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8080
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8081 The Emacs 22 version of that function uses @code{condition-case} and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8082 @code{copy-region-as-kill}, both of which we will explain.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8083 @code{condition-case} is an important special form.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8084
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8085 In essence, the @code{kill-region} function calls
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8086 @code{condition-case}, which takes three arguments. In this function,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8087 the first argument does nothing. The second argument contains the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8088 code that does the work when all goes well. The third argument
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8089 contains the code that is called in the event of an error.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8090
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8091 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8092 * Complete kill-region:: The function definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8093 * condition-case:: Dealing with a problem.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8094 * Lisp macro::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8095 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8096
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8097 @node Complete kill-region, condition-case, kill-region, kill-region
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8098 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8099 @unnumberedsubsec The Complete @code{kill-region} Definition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8100 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8101
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8102 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8103 We will go through the @code{condition-case} code in a moment. First,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8104 let us look at the definition of @code{kill-region}, with comments
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8105 added:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8106
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8107 @c GNU Emacs 22:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8108 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8109 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8110 (defun kill-region (beg end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8111 "Kill (\"cut\") text between point and mark.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8112 This deletes the text from the buffer and saves it in the kill ring.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8113 The command \\[yank] can retrieve it from there. @dots{} "
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8114 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8115
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8116 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8117 ;; @bullet{} Since order matters, pass point first.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8118 (interactive (list (point) (mark)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8119 ;; @bullet{} And tell us if we cannot cut the text.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8120 ;; `unless' is an `if' without a then-part.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8121 (unless (and beg end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8122 (error "The mark is not set now, so there is no region"))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8123 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8124
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8125 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8126 ;; @bullet{} `condition-case' takes three arguments.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8127 ;; If the first argument is nil, as it is here,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8128 ;; information about the error signal is not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8129 ;; stored for use by another function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8130 (condition-case nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8131 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8132
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8133 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8134 ;; @bullet{} The second argument to `condition-case' tells the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8135 ;; Lisp interpreter what to do when all goes well.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8136 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8137
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8138 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8139 ;; It starts with a `let' function that extracts the string
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8140 ;; and tests whether it exists. If so (that is what the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8141 ;; `when' checks), it calls an `if' function that determines
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8142 ;; whether the previous command was another call to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8143 ;; `kill-region'; if it was, then the new text is appended to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8144 ;; the previous text; if not, then a different function,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8145 ;; `kill-new', is called.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8146 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8147
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8148 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8149 ;; The `kill-append' function concatenates the new string and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8150 ;; the old. The `kill-new' function inserts text into a new
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8151 ;; item in the kill ring.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8152 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8153
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8154 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8155 ;; `when' is an `if' without an else-part. The second `when'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8156 ;; again checks whether the current string exists; in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8157 ;; addition, it checks whether the previous command was
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8158 ;; another call to `kill-region'. If one or the other
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8159 ;; condition is true, then it sets the current command to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8160 ;; be `kill-region'.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8161 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8162 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8163 (let ((string (filter-buffer-substring beg end t)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8164 (when string ;STRING is nil if BEG = END
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8165 ;; Add that string to the kill ring, one way or another.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8166 (if (eq last-command 'kill-region)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8167 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8168 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8169 ;; @minus{} `yank-handler' is an optional argument to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8170 ;; `kill-region' that tells the `kill-append' and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8171 ;; `kill-new' functions how deal with properties
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8172 ;; added to the text, such as `bold' or `italics'.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8173 (kill-append string (< end beg) yank-handler)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8174 (kill-new string nil yank-handler)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8175 (when (or string (eq last-command 'kill-region))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8176 (setq this-command 'kill-region))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8177 nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8178 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8179
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8180 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8181 ;; @bullet{} The third argument to `condition-case' tells the interpreter
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8182 ;; what to do with an error.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8183 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8184 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8185 ;; The third argument has a conditions part and a body part.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8186 ;; If the conditions are met (in this case,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8187 ;; if text or buffer are read-only)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8188 ;; then the body is executed.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8189 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8190 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8191 ;; The first part of the third argument is the following:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8192 ((buffer-read-only text-read-only) ;; the if-part
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8193 ;; @dots{} the then-part
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8194 (copy-region-as-kill beg end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8195 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8196 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8197 ;; Next, also as part of the then-part, set this-command, so
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8198 ;; it will be set in an error
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8199 (setq this-command 'kill-region)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8200 ;; Finally, in the then-part, send a message if you may copy
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8201 ;; the text to the kill ring without signally an error, but
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8202 ;; don't if you may not.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8203 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8204 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8205 (if kill-read-only-ok
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8206 (progn (message "Read only text copied to kill ring") nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8207 (barf-if-buffer-read-only)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8208 ;; If the buffer isn't read-only, the text is.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8209 (signal 'text-read-only (list (current-buffer)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8210 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8211 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8212
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8213 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8214 @c v 21
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8215 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8216 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8217 (defun kill-region (beg end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8218 "Kill between point and mark.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8219 The text is deleted but saved in the kill ring."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8220 (interactive "r")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8221 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8222
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8223 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8224 ;; 1. `condition-case' takes three arguments.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8225 ;; If the first argument is nil, as it is here,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8226 ;; information about the error signal is not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8227 ;; stored for use by another function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8228 (condition-case nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8229 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8230
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8231 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8232 ;; 2. The second argument to `condition-case'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8233 ;; tells the Lisp interpreter what to do when all goes well.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8234 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8235
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8236 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8237 ;; The `delete-and-extract-region' function usually does the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8238 ;; work. If the beginning and ending of the region are both
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8239 ;; the same, then the variable `string' will be empty, or nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8240 (let ((string (delete-and-extract-region beg end)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8241 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8242
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8243 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8244 ;; `when' is an `if' clause that cannot take an `else-part'.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8245 ;; Emacs normally sets the value of `last-command' to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8246 ;; previous command.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8247 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8248 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8249 ;; `kill-append' concatenates the new string and the old.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8250 ;; `kill-new' inserts text into a new item in the kill ring.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8251 (when string
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8252 (if (eq last-command 'kill-region)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8253 ;; if true, prepend string
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8254 (kill-append string (< end beg))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8255 (kill-new string)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8256 (setq this-command 'kill-region))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8257 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8258
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8259 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8260 ;; 3. The third argument to `condition-case' tells the interpreter
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8261 ;; what to do with an error.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8262 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8263 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8264 ;; The third argument has a conditions part and a body part.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8265 ;; If the conditions are met (in this case,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8266 ;; if text or buffer are read-only)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8267 ;; then the body is executed.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8268 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8269 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8270 ((buffer-read-only text-read-only) ;; this is the if-part
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8271 ;; then...
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8272 (copy-region-as-kill beg end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8273 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8274 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8275 (if kill-read-only-ok ;; usually this variable is nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8276 (message "Read only text copied to kill ring")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8277 ;; or else, signal an error if the buffer is read-only;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8278 (barf-if-buffer-read-only)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8279 ;; and, in any case, signal that the text is read-only.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8280 (signal 'text-read-only (list (current-buffer)))))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8281 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8282 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8283 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8284
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8285 @node condition-case, Lisp macro, Complete kill-region, kill-region
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8286 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8287 @subsection @code{condition-case}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8288 @findex condition-case
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8289
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8290 As we have seen earlier (@pxref{Making Errors, , Generate an Error
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8291 Message}), when the Emacs Lisp interpreter has trouble evaluating an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8292 expression, it provides you with help; in the jargon, this is called
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8293 ``signaling an error''. Usually, the computer stops the program and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8294 shows you a message.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8295
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8296 However, some programs undertake complicated actions. They should not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8297 simply stop on an error. In the @code{kill-region} function, the most
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8298 likely error is that you will try to kill text that is read-only and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8299 cannot be removed. So the @code{kill-region} function contains code
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8300 to handle this circumstance. This code, which makes up the body of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8301 the @code{kill-region} function, is inside of a @code{condition-case}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8302 special form.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8303
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8304 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8305 The template for @code{condition-case} looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8306
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8307 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8308 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8309 (condition-case
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8310 @var{var}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8311 @var{bodyform}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8312 @var{error-handler}@dots{})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8313 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8314 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8315
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8316 The second argument, @var{bodyform}, is straightforward. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8317 @code{condition-case} special form causes the Lisp interpreter to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8318 evaluate the code in @var{bodyform}. If no error occurs, the special
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8319 form returns the code's value and produces the side-effects, if any.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8320
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8321 In short, the @var{bodyform} part of a @code{condition-case}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8322 expression determines what should happen when everything works
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8323 correctly.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8324
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8325 However, if an error occurs, among its other actions, the function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8326 generating the error signal will define one or more error condition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8327 names.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8328
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8329 An error handler is the third argument to @code{condition case}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8330 An error handler has two parts, a @var{condition-name} and a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8331 @var{body}. If the @var{condition-name} part of an error handler
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8332 matches a condition name generated by an error, then the @var{body}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8333 part of the error handler is run.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8334
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8335 As you will expect, the @var{condition-name} part of an error handler
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8336 may be either a single condition name or a list of condition names.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8337
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8338 Also, a complete @code{condition-case} expression may contain more
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8339 than one error handler. When an error occurs, the first applicable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8340 handler is run.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8341
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8342 Lastly, the first argument to the @code{condition-case} expression,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8343 the @var{var} argument, is sometimes bound to a variable that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8344 contains information about the error. However, if that argument is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8345 nil, as is the case in @code{kill-region}, that information is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8346 discarded.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8347
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8348 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8349 In brief, in the @code{kill-region} function, the code
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8350 @code{condition-case} works like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8351
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8352 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8353 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8354 @var{If no errors}, @var{run only this code}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8355 @var{but}, @var{if errors}, @var{run this other code}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8356 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8357 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8358
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8359 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8360 2006 Oct 24
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8361 In Emacs 22,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8362 copy-region-as-kill is short, 12 lines, and uses
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8363 filter-buffer-substring, which is longer, 39 lines
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8364 and has delete-and-extract-region in it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8365 delete-and-extract-region is written in C.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8366
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8367 see Initializing a Variable with @code{defvar}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8368 this is line 8054
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8369 Initializing a Variable with @code{defvar} includes line 8350
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8370 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8371
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8372 @node Lisp macro, , condition-case, kill-region
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8373 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8374 @subsection Lisp macro
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8375 @cindex Macro, lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8376 @cindex Lisp macro
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8377
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8378 The part of the @code{condition-case} expression that is evaluated in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8379 the expectation that all goes well has a @code{when}. The code uses
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8380 @code{when} to determine whether the @code{string} variable points to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8381 text that exists.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8382
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8383 A @code{when} expression is simply a programmers' convenience. It is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8384 an @code{if} without the possibility of an else clause. In your mind,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8385 you can replace @code{when} with @code{if} and understand what goes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8386 on. That is what the Lisp interpreter does.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8387
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8388 Technically speaking, @code{when} is a Lisp macro. A Lisp @dfn{macro}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8389 enables you to define new control constructs and other language
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8390 features. It tells the interpreter how to compute another Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8391 expression which will in turn compute the value. In this case, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8392 `other expression' is an @code{if} expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8393
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8394 The @code{kill-region} function definition also has an @code{unless}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8395 macro; it is the converse of @code{when}. The @code{unless} macro is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8396 an @code{if} without a then clause
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8397
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8398 For more about Lisp macros, see @ref{Macros, , Macros, elisp, The GNU
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8399 Emacs Lisp Reference Manual}. The C programming language also
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8400 provides macros. These are different, but also useful.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8401
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8402 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8403 We will briefly look at C macros in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8404 @ref{Digression into C}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8405 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8406
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8407 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8408 Regarding the @code{when} macro, in the @code{condition-case}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8409 expression, when the string has content, then another conditional
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8410 expression is executed. This is an @code{if} with both a then-part
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8411 and an else-part.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8412
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8413 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8414 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8415 (if (eq last-command 'kill-region)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8416 (kill-append string (< end beg) yank-handler)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8417 (kill-new string nil yank-handler))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8418 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8419 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8420
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8421 The then-part is evaluated if the previous command was another call to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8422 @code{kill-region}; if not, the else-part is evaluated.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8423
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8424 @code{yank-handler} is an optional argument to @code{kill-region} that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8425 tells the @code{kill-append} and @code{kill-new} functions how deal
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8426 with properties added to the text, such as `bold' or `italics'.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8427
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8428 @code{last-command} is a variable that comes with Emacs that we have
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8429 not seen before. Normally, whenever a function is executed, Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8430 sets the value of @code{last-command} to the previous command.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8431
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8432 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8433 In this segment of the definition, the @code{if} expression checks
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8434 whether the previous command was @code{kill-region}. If it was,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8435
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8436 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8437 (kill-append string (< end beg) yank-handler)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8438 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8439
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8440 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8441 concatenates a copy of the newly clipped text to the just previously
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8442 clipped text in the kill ring.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8443
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8444 @node copy-region-as-kill, Digression into C, kill-region, Cutting & Storing Text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8445 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8446 @section @code{copy-region-as-kill}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8447 @findex copy-region-as-kill
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8448 @findex nthcdr
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8449
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8450 The @code{copy-region-as-kill} function copies a region of text from a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8451 buffer and (via either @code{kill-append} or @code{kill-new}) saves it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8452 in the @code{kill-ring}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8453
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8454 If you call @code{copy-region-as-kill} immediately after a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8455 @code{kill-region} command, Emacs appends the newly copied text to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8456 previously copied text. This means that if you yank back the text, you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8457 get it all, from both this and the previous operation. On the other
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8458 hand, if some other command precedes the @code{copy-region-as-kill},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8459 the function copies the text into a separate entry in the kill ring.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8460
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8461 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8462 * Complete copy-region-as-kill:: The complete function definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8463 * copy-region-as-kill body:: The body of @code{copy-region-as-kill}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8464 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8465
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8466 @node Complete copy-region-as-kill, copy-region-as-kill body, copy-region-as-kill, copy-region-as-kill
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8467 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8468 @unnumberedsubsec The complete @code{copy-region-as-kill} function definition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8469 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8470
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8471 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8472 Here is the complete text of the version 22 @code{copy-region-as-kill}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8473 function:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8474
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8475 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8476 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8477 (defun copy-region-as-kill (beg end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8478 "Save the region as if killed, but don't kill it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8479 In Transient Mark mode, deactivate the mark.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8480 If `interprogram-cut-function' is non-nil, also save the text for a window
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8481 system cut and paste."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8482 (interactive "r")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8483 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8484 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8485 (if (eq last-command 'kill-region)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8486 (kill-append (filter-buffer-substring beg end) (< end beg))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8487 (kill-new (filter-buffer-substring beg end)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8488 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8489 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8490 (if transient-mark-mode
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8491 (setq deactivate-mark t))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8492 nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8493 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8494 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8495
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8496 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8497 As usual, this function can be divided into its component parts:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8498
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8499 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8500 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8501 (defun copy-region-as-kill (@var{argument-list})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8502 "@var{documentation}@dots{}"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8503 (interactive "r")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8504 @var{body}@dots{})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8505 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8506 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8507
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8508 The arguments are @code{beg} and @code{end} and the function is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8509 interactive with @code{"r"}, so the two arguments must refer to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8510 beginning and end of the region. If you have been reading though this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8511 document from the beginning, understanding these parts of a function is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8512 almost becoming routine.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8513
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8514 The documentation is somewhat confusing unless you remember that the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8515 word `kill' has a meaning different from usual. The `Transient Mark'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8516 and @code{interprogram-cut-function} comments explain certain
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8517 side-effects.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8518
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8519 After you once set a mark, a buffer always contains a region. If you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8520 wish, you can use Transient Mark mode to highlight the region
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8521 temporarily. (No one wants to highlight the region all the time, so
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8522 Transient Mark mode highlights it only at appropriate times. Many
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8523 people turn off Transient Mark mode, so the region is never
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8524 highlighted.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8525
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8526 Also, a windowing system allows you to copy, cut, and paste among
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8527 different programs. In the X windowing system, for example, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8528 @code{interprogram-cut-function} function is @code{x-select-text},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8529 which works with the windowing system's equivalent of the Emacs kill
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8530 ring.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8531
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8532 The body of the @code{copy-region-as-kill} function starts with an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8533 @code{if} clause. What this clause does is distinguish between two
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8534 different situations: whether or not this command is executed
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8535 immediately after a previous @code{kill-region} command. In the first
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8536 case, the new region is appended to the previously copied text.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8537 Otherwise, it is inserted into the beginning of the kill ring as a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8538 separate piece of text from the previous piece.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8539
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8540 The last two lines of the function prevent the region from lighting up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8541 if Transient Mark mode is turned on.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8542
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8543 The body of @code{copy-region-as-kill} merits discussion in detail.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8544
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8545 @node copy-region-as-kill body, , Complete copy-region-as-kill, copy-region-as-kill
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8546 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8547 @subsection The Body of @code{copy-region-as-kill}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8548
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8549 The @code{copy-region-as-kill} function works in much the same way as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8550 the @code{kill-region} function. Both are written so that two or more
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8551 kills in a row combine their text into a single entry. If you yank
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8552 back the text from the kill ring, you get it all in one piece.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8553 Moreover, kills that kill forward from the current position of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8554 cursor are added to the end of the previously copied text and commands
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8555 that copy text backwards add it to the beginning of the previously
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8556 copied text. This way, the words in the text stay in the proper
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8557 order.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8558
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8559 Like @code{kill-region}, the @code{copy-region-as-kill} function makes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8560 use of the @code{last-command} variable that keeps track of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8561 previous Emacs command.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8562
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8563 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8564 * last-command & this-command::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8565 * kill-append function::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8566 * kill-new function::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8567 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8568
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8569 @node last-command & this-command, kill-append function, copy-region-as-kill body, copy-region-as-kill body
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8570 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8571 @unnumberedsubsubsec @code{last-command} and @code{this-command}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8572 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8573
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8574 Normally, whenever a function is executed, Emacs sets the value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8575 @code{this-command} to the function being executed (which in this case
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8576 would be @code{copy-region-as-kill}). At the same time, Emacs sets
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8577 the value of @code{last-command} to the previous value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8578 @code{this-command}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8579
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8580 In the first part of the body of the @code{copy-region-as-kill}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8581 function, an @code{if} expression determines whether the value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8582 @code{last-command} is @code{kill-region}. If so, the then-part of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8583 the @code{if} expression is evaluated; it uses the @code{kill-append}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8584 function to concatenate the text copied at this call to the function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8585 with the text already in the first element (the @sc{car}) of the kill
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8586 ring. On the other hand, if the value of @code{last-command} is not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8587 @code{kill-region}, then the @code{copy-region-as-kill} function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8588 attaches a new element to the kill ring using the @code{kill-new}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8589 function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8590
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8591 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8592 The @code{if} expression reads as follows; it uses @code{eq}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8593
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8594 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8595 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8596 (if (eq last-command 'kill-region)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8597 ;; @r{then-part}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8598 (kill-append (filter-buffer-substring beg end) (< end beg))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8599 ;; @r{else-part}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8600 (kill-new (filter-buffer-substring beg end)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8601 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8602 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8603
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8604 @findex filter-buffer-substring
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8605 (The @code{filter-buffer-substring} function returns a filtered
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8606 substring of the buffer, if any. Optionally---the arguments are not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8607 here, so neither is done---the function may delete the initial text or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8608 return the text without its properties; this function is a replacement
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8609 for the older @code{buffer-substring} function, which came before text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8610 properties were implemented.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8611
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8612 @findex eq @r{(example of use)}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8613 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8614 The @code{eq} function tests whether its first argument is the same Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8615 object as its second argument. The @code{eq} function is similar to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8616 @code{equal} function in that it is used to test for equality, but
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8617 differs in that it determines whether two representations are actually
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8618 the same object inside the computer, but with different names.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8619 @code{equal} determines whether the structure and contents of two
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8620 expressions are the same.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8621
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8622 If the previous command was @code{kill-region}, then the Emacs Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8623 interpreter calls the @code{kill-append} function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8624
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8625 @node kill-append function, kill-new function, last-command & this-command, copy-region-as-kill body
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8626 @unnumberedsubsubsec The @code{kill-append} function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8627 @findex kill-append
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8628
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8629 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8630 The @code{kill-append} function looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8631
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8632 @c in GNU Emacs 22
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8633 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8634 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8635 (defun kill-append (string before-p &optional yank-handler)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8636 "Append STRING to the end of the latest kill in the kill ring.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8637 If BEFORE-P is non-nil, prepend STRING to the kill.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8638 @dots{} "
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8639 (let* ((cur (car kill-ring)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8640 (kill-new (if before-p (concat string cur) (concat cur string))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8641 (or (= (length cur) 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8642 (equal yank-handler
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8643 (get-text-property 0 'yank-handler cur)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8644 yank-handler)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8645 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8646 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8647
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8648 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8649 was:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8650 (defun kill-append (string before-p)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8651 "Append STRING to the end of the latest kill in the kill ring.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8652 If BEFORE-P is non-nil, prepend STRING to the kill.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8653 If `interprogram-cut-function' is set, pass the resulting kill to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8654 it."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8655 (kill-new (if before-p
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8656 (concat string (car kill-ring))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8657 (concat (car kill-ring) string))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8658 t))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8659 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8660
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8661 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8662 The @code{kill-append} function is fairly straightforward. It uses
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8663 the @code{kill-new} function, which we will discuss in more detail in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8664 a moment.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8665
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8666 (Also, the function provides an optional argument called
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8667 @code{yank-handler}; when invoked, this argument tells the function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8668 how to deal with properties added to the text, such as `bold' or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8669 `italics'.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8670
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8671 @c !!! bug in GNU Emacs 22 version of kill-append ?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8672 It has a @code{let*} function to set the value of the first element of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8673 the kill ring to @code{cur}. (I do not know why the function does not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8674 use @code{let} instead; only one value is set in the expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8675 Perhaps this is a bug that produces no problems?)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8676
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8677 Consider the conditional that is one of the two arguments to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8678 @code{kill-new}. It uses @code{concat} to concatenate the new text to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8679 the @sc{car} of the kill ring. Whether it prepends or appends the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8680 text depends on the results of an @code{if} expression:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8681
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8682 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8683 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8684 (if before-p ; @r{if-part}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8685 (concat string cur) ; @r{then-part}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8686 (concat cur string)) ; @r{else-part}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8687 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8688 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8689
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8690 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8691 If the region being killed is before the region that was killed in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8692 last command, then it should be prepended before the material that was
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8693 saved in the previous kill; and conversely, if the killed text follows
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8694 what was just killed, it should be appended after the previous text.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8695 The @code{if} expression depends on the predicate @code{before-p} to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8696 decide whether the newly saved text should be put before or after the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8697 previously saved text.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8698
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8699 The symbol @code{before-p} is the name of one of the arguments to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8700 @code{kill-append}. When the @code{kill-append} function is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8701 evaluated, it is bound to the value returned by evaluating the actual
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8702 argument. In this case, this is the expression @code{(< end beg)}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8703 This expression does not directly determine whether the killed text in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8704 this command is located before or after the kill text of the last
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8705 command; what it does is determine whether the value of the variable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8706 @code{end} is less than the value of the variable @code{beg}. If it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8707 is, it means that the user is most likely heading towards the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8708 beginning of the buffer. Also, the result of evaluating the predicate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8709 expression, @code{(< end beg)}, will be true and the text will be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8710 prepended before the previous text. On the other hand, if the value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8711 the variable @code{end} is greater than the value of the variable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8712 @code{beg}, the text will be appended after the previous text.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8713
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8714 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8715 When the newly saved text will be prepended, then the string with the new
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8716 text will be concatenated before the old text:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8717
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8718 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8719 (concat string cur)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8720 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8721
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8722 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8723 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8724 But if the text will be appended, it will be concatenated
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8725 after the old text:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8726
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8727 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8728 (concat cur string))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8729 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8730
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8731 To understand how this works, we first need to review the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8732 @code{concat} function. The @code{concat} function links together or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8733 unites two strings of text. The result is a string. For example:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8734
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8735 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8736 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8737 (concat "abc" "def")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8738 @result{} "abcdef"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8739 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8740
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8741 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8742 (concat "new "
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8743 (car '("first element" "second element")))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8744 @result{} "new first element"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8745
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8746 (concat (car
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8747 '("first element" "second element")) " modified")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8748 @result{} "first element modified"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8749 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8750 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8751
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8752 We can now make sense of @code{kill-append}: it modifies the contents
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8753 of the kill ring. The kill ring is a list, each element of which is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8754 saved text. The @code{kill-append} function uses the @code{kill-new}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8755 function which in turn uses the @code{setcar} function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8756
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8757 @node kill-new function, , kill-append function, copy-region-as-kill body
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8758 @unnumberedsubsubsec The @code{kill-new} function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8759 @findex kill-new
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8760
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8761 @c in GNU Emacs 22, additional documentation to kill-new:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8762 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8763 Optional third arguments YANK-HANDLER controls how the STRING is later
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8764 inserted into a buffer; see `insert-for-yank' for details.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8765 When a yank handler is specified, STRING must be non-empty (the yank
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8766 handler, if non-nil, is stored as a `yank-handler' text property on STRING).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8767
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8768 When the yank handler has a non-nil PARAM element, the original STRING
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8769 argument is not used by `insert-for-yank'. However, since Lisp code
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8770 may access and use elements from the kill ring directly, the STRING
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8771 argument should still be a \"useful\" string for such uses."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8772 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8773 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8774 The @code{kill-new} function looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8775
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8776 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8777 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8778 (defun kill-new (string &optional replace yank-handler)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8779 "Make STRING the latest kill in the kill ring.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8780 Set `kill-ring-yank-pointer' to point to it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8781
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8782 If `interprogram-cut-function' is non-nil, apply it to STRING.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8783 Optional second argument REPLACE non-nil means that STRING will replace
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8784 the front of the kill ring, rather than being added to the list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8785 @dots{}"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8786 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8787 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8788 (if (> (length string) 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8789 (if yank-handler
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8790 (put-text-property 0 (length string)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8791 'yank-handler yank-handler string))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8792 (if yank-handler
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8793 (signal 'args-out-of-range
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8794 (list string "yank-handler specified for empty string"))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8795 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8796 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8797 (if (fboundp 'menu-bar-update-yank-menu)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8798 (menu-bar-update-yank-menu string (and replace (car kill-ring))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8799 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8800 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8801 (if (and replace kill-ring)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8802 (setcar kill-ring string)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8803 (push string kill-ring)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8804 (if (> (length kill-ring) kill-ring-max)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8805 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8806 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8807 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8808 (setq kill-ring-yank-pointer kill-ring)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8809 (if interprogram-cut-function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8810 (funcall interprogram-cut-function string (not replace))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8811 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8812 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8813 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8814 was:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8815 (defun kill-new (string &optional replace)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8816 "Make STRING the latest kill in the kill ring.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8817 Set the kill-ring-yank pointer to point to it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8818 If `interprogram-cut-function' is non-nil, apply it to STRING.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8819 Optional second argument REPLACE non-nil means that STRING will replace
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8820 the front of the kill ring, rather than being added to the list."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8821 (and (fboundp 'menu-bar-update-yank-menu)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8822 (menu-bar-update-yank-menu string (and replace (car kill-ring))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8823 (if (and replace kill-ring)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8824 (setcar kill-ring string)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8825 (setq kill-ring (cons string kill-ring))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8826 (if (> (length kill-ring) kill-ring-max)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8827 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8828 (setq kill-ring-yank-pointer kill-ring)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8829 (if interprogram-cut-function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8830 (funcall interprogram-cut-function string (not replace))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8831 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8832
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8833 (Notice that the function is not interactive.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8834
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8835 As usual, we can look at this function in parts.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8836
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8837 The function definition has an optional @code{yank-handler} argument,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8838 which when invoked tells the function how to deal with properties
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8839 added to the text, such as `bold' or `italics'. We will skip that.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8840
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8841 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8842 The first line of the documentation makes sense:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8843
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8844 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8845 Make STRING the latest kill in the kill ring.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8846 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8847
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8848 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8849 Let's skip over the rest of the documentation for the moment.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8850
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8851 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8852 Also, let's skip over the initial @code{if} expression and those lines
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8853 of code involving @code{menu-bar-update-yank-menu}. We will explain
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8854 them below.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8855
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8856 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8857 The critical lines are these:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8858
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8859 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8860 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8861 (if (and replace kill-ring)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8862 ;; @r{then}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8863 (setcar kill-ring string)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8864 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8865 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8866 ;; @r{else}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8867 (push string kill-ring)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8868 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8869 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8870 (setq kill-ring (cons string kill-ring))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8871 (if (> (length kill-ring) kill-ring-max)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8872 ;; @r{avoid overly long kill ring}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8873 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8874 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8875 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8876 (setq kill-ring-yank-pointer kill-ring)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8877 (if interprogram-cut-function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8878 (funcall interprogram-cut-function string (not replace))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8879 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8880 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8881
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8882 The conditional test is @w{@code{(and replace kill-ring)}}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8883 This will be true when two conditions are met: the kill ring has
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8884 something in it, and the @code{replace} variable is true.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8885
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8886 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8887 When the @code{kill-append} function sets @code{replace} to be true
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8888 and when the kill ring has at least one item in it, the @code{setcar}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8889 expression is executed:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8890
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8891 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8892 (setcar kill-ring string)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8893 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8894
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8895 The @code{setcar} function actually changes the first element of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8896 @code{kill-ring} list to the value of @code{string}. It replaces the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8897 first element.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8898
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8899 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8900 On the other hand, if the kill ring is empty, or replace is false, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8901 else-part of the condition is executed:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8902
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8903 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8904 (push string kill-ring)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8905 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8906
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8907 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8908 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8909 @code{push} puts its first argument onto the second. It is similar to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8910 the older
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8911
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8912 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8913 (setq kill-ring (cons string kill-ring))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8914 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8915
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8916 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8917 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8918 or the newer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8919
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8920 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8921 (add-to-list kill-ring string)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8922 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8923
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8924 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8925 When it is false, the expression first constructs a new version of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8926 kill ring by prepending @code{string} to the existing kill ring as a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8927 new element (that is what the @code{push} does). Then it executes a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8928 second @code{if} clause. This second @code{if} clause keeps the kill
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8929 ring from growing too long.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8930
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8931 Let's look at these two expressions in order.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8932
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8933 The @code{push} line of the else-part sets the new value of the kill
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8934 ring to what results from adding the string being killed to the old
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8935 kill ring.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8936
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8937 We can see how this works with an example.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8938
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8939 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8940 First,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8941
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8942 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8943 (setq example-list '("here is a clause" "another clause"))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8944 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8945
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8946 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8947 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8948 After evaluating this expression with @kbd{C-x C-e}, you can evaluate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8949 @code{example-list} and see what it returns:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8950
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8951 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8952 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8953 example-list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8954 @result{} ("here is a clause" "another clause")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8955 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8956 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8957
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8958 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8959 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8960 Now, we can add a new element on to this list by evaluating the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8961 following expression:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8962 @findex push, @r{example}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8963
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8964 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8965 (push "a third clause" example-list)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8966 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8967
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8968 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8969 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8970 When we evaluate @code{example-list}, we find its value is:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8971
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8972 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8973 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8974 example-list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8975 @result{} ("a third clause" "here is a clause" "another clause")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8976 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8977 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8978
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8979 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8980 Thus, the third clause is added to the list by @code{push}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8981
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8982 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8983 Now for the second part of the @code{if} clause. This expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8984 keeps the kill ring from growing too long. It looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8985
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8986 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8987 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8988 (if (> (length kill-ring) kill-ring-max)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8989 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8990 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8991 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8992
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8993 The code checks whether the length of the kill ring is greater than
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8994 the maximum permitted length. This is the value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8995 @code{kill-ring-max} (which is 60, by default). If the length of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8996 kill ring is too long, then this code sets the last element of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8997 kill ring to @code{nil}. It does this by using two functions,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8998 @code{nthcdr} and @code{setcdr}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8999
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9000 We looked at @code{setcdr} earlier (@pxref{setcdr, , @code{setcdr}}).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9001 It sets the @sc{cdr} of a list, just as @code{setcar} sets the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9002 @sc{car} of a list. In this case, however, @code{setcdr} will not be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9003 setting the @sc{cdr} of the whole kill ring; the @code{nthcdr}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9004 function is used to cause it to set the @sc{cdr} of the next to last
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9005 element of the kill ring---this means that since the @sc{cdr} of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9006 next to last element is the last element of the kill ring, it will set
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9007 the last element of the kill ring.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9008
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9009 @findex nthcdr, @r{example}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9010 The @code{nthcdr} function works by repeatedly taking the @sc{cdr} of a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9011 list---it takes the @sc{cdr} of the @sc{cdr} of the @sc{cdr}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9012 @dots{} It does this @var{N} times and returns the results.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9013 (@xref{nthcdr, , @code{nthcdr}}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9014
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9015 @findex setcdr, @r{example}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9016 Thus, if we had a four element list that was supposed to be three
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9017 elements long, we could set the @sc{cdr} of the next to last element
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9018 to @code{nil}, and thereby shorten the list. (If you set the last
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9019 element to some other value than @code{nil}, which you could do, then
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9020 you would not have shortened the list. @xref{setcdr, ,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9021 @code{setcdr}}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9022
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9023 You can see shortening by evaluating the following three expressions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9024 in turn. First set the value of @code{trees} to @code{(maple oak pine
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9025 birch)}, then set the @sc{cdr} of its second @sc{cdr} to @code{nil}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9026 and then find the value of @code{trees}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9027
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9028 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9029 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9030 (setq trees '(maple oak pine birch))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9031 @result{} (maple oak pine birch)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9032 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9033
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9034 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9035 (setcdr (nthcdr 2 trees) nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9036 @result{} nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9037
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9038 trees
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9039 @result{} (maple oak pine)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9040 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9041 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9042
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9043 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9044 (The value returned by the @code{setcdr} expression is @code{nil} since
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9045 that is what the @sc{cdr} is set to.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9046
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9047 To repeat, in @code{kill-new}, the @code{nthcdr} function takes the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9048 @sc{cdr} a number of times that is one less than the maximum permitted
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9049 size of the kill ring and @code{setcdr} sets the @sc{cdr} of that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9050 element (which will be the rest of the elements in the kill ring) to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9051 @code{nil}. This prevents the kill ring from growing too long.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9052
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9053 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9054 The next to last expression in the @code{kill-new} function is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9055
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9056 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9057 (setq kill-ring-yank-pointer kill-ring)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9058 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9059
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9060 The @code{kill-ring-yank-pointer} is a global variable that is set to be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9061 the @code{kill-ring}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9062
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9063 Even though the @code{kill-ring-yank-pointer} is called a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9064 @samp{pointer}, it is a variable just like the kill ring. However, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9065 name has been chosen to help humans understand how the variable is used.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9066
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9067 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9068 Now, to return to an early expression in the body of the function:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9069
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9070 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9071 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9072 (if (fboundp 'menu-bar-update-yank-menu)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9073 (menu-bar-update-yank-menu string (and replace (car kill-ring))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9074 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9075 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9076
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9077 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9078 It starts with an @code{if} expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9079
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9080 In this case, the expression tests first to see whether
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9081 @code{menu-bar-update-yank-menu} exists as a function, and if so,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9082 calls it. The @code{fboundp} function returns true if the symbol it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9083 is testing has a function definition that `is not void'. If the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9084 symbol's function definition were void, we would receive an error
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9085 message, as we did when we created errors intentionally (@pxref{Making
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9086 Errors, , Generate an Error Message}).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9087
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9088 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9089 The then-part contains an expression whose first element is the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9090 function @code{and}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9091
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9092 @findex and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9093 The @code{and} special form evaluates each of its arguments until one
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9094 of the arguments returns a value of @code{nil}, in which case the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9095 @code{and} expression returns @code{nil}; however, if none of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9096 arguments returns a value of @code{nil}, the value resulting from
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9097 evaluating the last argument is returned. (Since such a value is not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9098 @code{nil}, it is considered true in Emacs Lisp.) In other words, an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9099 @code{and} expression returns a true value only if all its arguments
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9100 are true. (@xref{Second Buffer Related Review}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9101
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9102 The expression determines whether the second argument to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9103 @code{menu-bar-update-yank-menu} is true or not.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9104 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9105 ;; If we're supposed to be extending an existing string, and that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9106 ;; string really is at the front of the menu, then update it in place.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9107 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9108
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9109 @code{menu-bar-update-yank-menu} is one of the functions that make it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9110 possible to use the `Select and Paste' menu in the Edit item of a menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9111 bar; using a mouse, you can look at the various pieces of text you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9112 have saved and select one piece to paste.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9113
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9114 The last expression in the @code{kill-new} function adds the newly
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9115 copied string to whatever facility exists for copying and pasting
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9116 among different programs running in a windowing system. In the X
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9117 Windowing system, for example, the @code{x-select-text} function takes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9118 the string and stores it in memory operated by X. You can paste the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9119 string in another program, such as an Xterm.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9120
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9121 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9122 The expression looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9123
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9124 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9125 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9126 (if interprogram-cut-function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9127 (funcall interprogram-cut-function string (not replace))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9128 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9129 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9130
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9131 If an @code{interprogram-cut-function} exists, then Emacs executes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9132 @code{funcall}, which in turn calls its first argument as a function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9133 and passes the remaining arguments to it. (Incidentally, as far as I
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9134 can see, this @code{if} expression could be replaced by an @code{and}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9135 expression similar to the one in the first part of the function.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9136
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9137 We are not going to discuss windowing systems and other programs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9138 further, but merely note that this is a mechanism that enables GNU
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9139 Emacs to work easily and well with other programs.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9140
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9141 This code for placing text in the kill ring, either concatenated with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9142 an existing element or as a new element, leads us to the code for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9143 bringing back text that has been cut out of the buffer---the yank
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9144 commands. However, before discussing the yank commands, it is better
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9145 to learn how lists are implemented in a computer. This will make
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9146 clear such mysteries as the use of the term `pointer'. But before
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9147 that, we will digress into C.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9148
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9149 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9150 @c is this true in Emacs 22? Does not seems to be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9151
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9152 (If the @w{@code{(< end beg))}}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9153 expression is true, @code{kill-append} prepends the string to the just
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9154 previously clipped text. For a detailed discussion, see
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9155 @ref{kill-append function, , The @code{kill-append} function}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9156
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9157 If you then yank back the text, i.e., `paste' it, you get both
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9158 pieces of text at once. That way, if you delete two words in a row,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9159 and then yank them back, you get both words, in their proper order,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9160 with one yank. (The @w{@code{(< end beg))}} expression makes sure the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9161 order is correct.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9162
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9163 On the other hand, if the previous command is not @code{kill-region},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9164 then the @code{kill-new} function is called, which adds the text to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9165 the kill ring as the latest item, and sets the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9166 @code{kill-ring-yank-pointer} variable to point to it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9167 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9168 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9169
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9170 @c Evidently, changed for Emacs 22. The zap-to-char command does not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9171 @c use the delete-and-extract-region function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9172
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9173 2006 Oct 26, the Digression into C is now OK but should come after
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9174 copy-region-as-kill and filter-buffer-substring
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9175
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9176 2006 Oct 24
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9177 In Emacs 22,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9178 copy-region-as-kill is short, 12 lines, and uses
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9179 filter-buffer-substring, which is longer, 39 lines
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9180 and has delete-and-extract-region in it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9181 delete-and-extract-region is written in C.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9182
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9183 see Initializing a Variable with @code{defvar}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9184 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9185
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9186 @node Digression into C, defvar, copy-region-as-kill, Cutting & Storing Text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9187 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9188 @section Digression into C
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9189 @findex delete-and-extract-region
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9190 @cindex C, a digression into
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9191 @cindex Digression into C
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9192
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9193 The @code{copy-region-as-kill} function (@pxref{copy-region-as-kill, ,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9194 @code{copy-region-as-kill}}) uses the @code{filter-buffer-substring}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9195 function, which in turn uses the @code{delete-and-extract-region}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9196 function. It removes the contents of a region and you cannot get them
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9197 back.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9198
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9199 Unlike the other code discussed here, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9200 @code{delete-and-extract-region} function is not written in Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9201 Lisp; it is written in C and is one of the primitives of the GNU Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9202 system. Since it is very simple, I will digress briefly from Lisp and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9203 describe it here.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9204
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9205 @c GNU Emacs 22 in /usr/local/src/emacs/src/editfns.c
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9206 @c the DEFUN for buffer-substring-no-properties
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9207
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9208 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9209 Like many of the other Emacs primitives,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9210 @code{delete-and-extract-region} is written as an instance of a C
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9211 macro, a macro being a template for code. The complete macro looks
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9212 like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9213
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9214 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9215 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9216 DEFUN ("buffer-substring-no-properties", Fbuffer_substring_no_properties,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9217 Sbuffer_substring_no_properties, 2, 2, 0,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9218 doc: /* Return the characters of part of the buffer,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9219 without the text properties.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9220 The two arguments START and END are character positions;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9221 they can be in either order. */)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9222 (start, end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9223 Lisp_Object start, end;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9224 @{
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9225 register int b, e;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9226
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9227 validate_region (&start, &end);
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9228 b = XINT (start);
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9229 e = XINT (end);
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9230
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9231 return make_buffer_string (b, e, 0);
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9232 @}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9233 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9234 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9235
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9236 Without going into the details of the macro writing process, let me
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9237 point out that this macro starts with the word @code{DEFUN}. The word
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9238 @code{DEFUN} was chosen since the code serves the same purpose as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9239 @code{defun} does in Lisp. (The @code{DEFUN} C macro is defined in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9240 @file{emacs/src/lisp.h}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9241
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9242 The word @code{DEFUN} is followed by seven parts inside of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9243 parentheses:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9244
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9245 @itemize @bullet
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9246 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9247 The first part is the name given to the function in Lisp,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9248 @code{delete-and-extract-region}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9249
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9250 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9251 The second part is the name of the function in C,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9252 @code{Fdelete_and_extract_region}. By convention, it starts with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9253 @samp{F}. Since C does not use hyphens in names, underscores are used
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9254 instead.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9255
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9256 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9257 The third part is the name for the C constant structure that records
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9258 information on this function for internal use. It is the name of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9259 function in C but begins with an @samp{S} instead of an @samp{F}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9260
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9261 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9262 The fourth and fifth parts specify the minimum and maximum number of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9263 arguments the function can have. This function demands exactly 2
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9264 arguments.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9265
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9266 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9267 The sixth part is nearly like the argument that follows the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9268 @code{interactive} declaration in a function written in Lisp: a letter
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9269 followed, perhaps, by a prompt. The only difference from the Lisp is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9270 when the macro is called with no arguments. Then you write a @code{0}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9271 (which is a `null string'), as in this macro.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9272
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9273 If you were to specify arguments, you would place them between
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9274 quotation marks. The C macro for @code{goto-char} includes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9275 @code{"NGoto char: "} in this position to indicate that the function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9276 expects a raw prefix, in this case, a numerical location in a buffer,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9277 and provides a prompt.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9278
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9279 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9280 The seventh part is a documentation string, just like the one for a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9281 function written in Emacs Lisp, except that every newline must be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9282 written explicitly as @samp{\n} followed by a backslash and carriage
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9283 return.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9284
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9285 @need 1000
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9286 Thus, the first two lines of documentation for @code{goto-char} are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9287 written like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9288
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9289 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9290 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9291 "Set point to POSITION, a number or marker.\n\
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9292 Beginning of buffer is position (point-min), end is (point-max)."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9293 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9294 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9295 @end itemize
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9296
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9297 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9298 In a C macro, the formal parameters come next, with a statement of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9299 what kind of object they are, followed by what might be called the `body'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9300 of the macro. For @code{delete-and-extract-region} the `body'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9301 consists of the following four lines:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9302
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9303 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9304 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9305 validate_region (&start, &end);
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9306 if (XINT (start) == XINT (end))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9307 return build_string ("");
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9308 return del_range_1 (XINT (start), XINT (end), 1, 1);
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9309 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9310 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9311
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9312 The @code{validate_region} function checks whether the values
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9313 passed as the beginning and end of the region are the proper type and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9314 are within range. If the beginning and end positions are the same,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9315 then return and empty string.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9316
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9317 The @code{del_range_1} function actually deletes the text. It is a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9318 complex function we will not look into. It updates the buffer and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9319 does other things. However, it is worth looking at the two arguments
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9320 passed to @code{del_range}. These are @w{@code{XINT (start)}} and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9321 @w{@code{XINT (end)}}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9322
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9323 As far as the C language is concerned, @code{start} and @code{end} are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9324 two integers that mark the beginning and end of the region to be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9325 deleted@footnote{More precisely, and requiring more expert knowledge
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9326 to understand, the two integers are of type `Lisp_Object', which can
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9327 also be a C union instead of an integer type.}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9328
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9329 In early versions of Emacs, these two numbers were thirty-two bits
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9330 long, but the code is slowly being generalized to handle other
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9331 lengths. Three of the available bits are used to specify the type of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9332 information; the remaining bits are used as `content'.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9333
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9334 @samp{XINT} is a C macro that extracts the relevant number from the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9335 longer collection of bits; the three other bits are discarded.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9336
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9337 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9338 The command in @code{delete-and-extract-region} looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9339
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9340 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9341 del_range_1 (XINT (start), XINT (end), 1, 1);
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9342 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9343
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9344 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9345 It deletes the region between the beginning position, @code{start},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9346 and the ending position, @code{end}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9347
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9348 From the point of view of the person writing Lisp, Emacs is all very
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9349 simple; but hidden underneath is a great deal of complexity to make it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9350 all work.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9351
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9352 @node defvar, cons & search-fwd Review, Digression into C, Cutting & Storing Text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9353 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9354 @section Initializing a Variable with @code{defvar}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9355 @findex defvar
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9356 @cindex Initializing a variable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9357 @cindex Variable initialization
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9358
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9359 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9360 2006 Oct 24
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9361 In Emacs 22,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9362 copy-region-as-kill is short, 12 lines, and uses
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9363 filter-buffer-substring, which is longer, 39 lines
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9364 and has delete-and-extract-region in it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9365 delete-and-extract-region is written in C.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9366
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9367 see Initializing a Variable with @code{defvar}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9368
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9369 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9370
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9371 The @code{copy-region-as-kill} function is written in Emacs Lisp. Two
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9372 functions within it, @code{kill-append} and @code{kill-new}, copy a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9373 region in a buffer and save it in a variable called the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9374 @code{kill-ring}. This section describes how the @code{kill-ring}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9375 variable is created and initialized using the @code{defvar} special
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9376 form.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9377
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9378 (Again we note that the term @code{kill-ring} is a misnomer. The text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9379 that is clipped out of the buffer can be brought back; it is not a ring
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9380 of corpses, but a ring of resurrectable text.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9381
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9382 In Emacs Lisp, a variable such as the @code{kill-ring} is created and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9383 given an initial value by using the @code{defvar} special form. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9384 name comes from ``define variable''.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9385
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9386 The @code{defvar} special form is similar to @code{setq} in that it sets
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9387 the value of a variable. It is unlike @code{setq} in two ways: first,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9388 it only sets the value of the variable if the variable does not already
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9389 have a value. If the variable already has a value, @code{defvar} does
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9390 not override the existing value. Second, @code{defvar} has a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9391 documentation string.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9392
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9393 (Another special form, @code{defcustom}, is designed for variables
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9394 that people customize. It has more features than @code{defvar}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9395 (@xref{defcustom, , Setting Variables with @code{defcustom}}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9396
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9397 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9398 * See variable current value::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9399 * defvar and asterisk::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9400 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9401
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9402 @node See variable current value, defvar and asterisk, defvar, defvar
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9403 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9404 @unnumberedsubsec Seeing the Current Value of a Variable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9405 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9406
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9407 You can see the current value of a variable, any variable, by using
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9408 the @code{describe-variable} function, which is usually invoked by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9409 typing @kbd{C-h v}. If you type @kbd{C-h v} and then @code{kill-ring}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9410 (followed by @key{RET}) when prompted, you will see what is in your
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9411 current kill ring---this may be quite a lot! Conversely, if you have
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9412 been doing nothing this Emacs session except read this document, you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9413 may have nothing in it. Also, you will see the documentation for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9414 @code{kill-ring}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9415
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9416 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9417 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9418 Documentation:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9419 List of killed text sequences.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9420 Since the kill ring is supposed to interact nicely with cut-and-paste
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9421 facilities offered by window systems, use of this variable should
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9422 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9423 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9424 interact nicely with `interprogram-cut-function' and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9425 `interprogram-paste-function'. The functions `kill-new',
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9426 `kill-append', and `current-kill' are supposed to implement this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9427 interaction; you may want to use them instead of manipulating the kill
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9428 ring directly.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9429 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9430 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9431
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9432 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9433 The kill ring is defined by a @code{defvar} in the following way:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9434
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9435 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9436 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9437 (defvar kill-ring nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9438 "List of killed text sequences.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9439 @dots{}")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9440 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9441 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9442
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9443 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9444 In this variable definition, the variable is given an initial value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9445 @code{nil}, which makes sense, since if you have saved nothing, you want
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9446 nothing back if you give a @code{yank} command. The documentation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9447 string is written just like the documentation string of a @code{defun}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9448 As with the documentation string of the @code{defun}, the first line of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9449 the documentation should be a complete sentence, since some commands,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9450 like @code{apropos}, print only the first line of documentation.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9451 Succeeding lines should not be indented; otherwise they look odd when
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9452 you use @kbd{C-h v} (@code{describe-variable}).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9453
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9454 @node defvar and asterisk, , See variable current value, defvar
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9455 @subsection @code{defvar} and an asterisk
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9456 @findex defvar @r{for a user customizable variable}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9457 @findex defvar @r{with an asterisk}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9458
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9459 In the past, Emacs used the @code{defvar} special form both for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9460 internal variables that you would not expect a user to change and for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9461 variables that you do expect a user to change. Although you can still
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9462 use @code{defvar} for user customizable variables, please use
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9463 @code{defcustom} instead, since that special form provides a path into
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9464 the Customization commands. (@xref{defcustom, , Specifying Variables
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9465 using @code{defcustom}}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9466
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9467 When you specified a variable using the @code{defvar} special form,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9468 you could distinguish a readily settable variable from others by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9469 typing an asterisk, @samp{*}, in the first column of its documentation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9470 string. For example:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9471
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9472 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9473 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9474 (defvar shell-command-default-error-buffer nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9475 "*Buffer name for `shell-command' @dots{} error output.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9476 @dots{} ")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9477 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9478 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9479
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9480 @findex set-variable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9481 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9482 You could (and still can) use the @code{set-variable} command to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9483 change the value of @code{shell-command-default-error-buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9484 temporarily. However, options set using @code{set-variable} are set
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9485 only for the duration of your editing session. The new values are not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9486 saved between sessions. Each time Emacs starts, it reads the original
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9487 value, unless you change the value within your @file{.emacs} file,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9488 either by setting it manually or by using @code{customize}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9489 @xref{Emacs Initialization, , Your @file{.emacs} File}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9490
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9491 For me, the major use of the @code{set-variable} command is to suggest
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9492 variables that I might want to set in my @file{.emacs} file. There
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9493 are now more than 700 such variables --- far too many to remember
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9494 readily. Fortunately, you can press @key{TAB} after calling the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9495 @code{M-x set-variable} command to see the list of variables.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9496 (@xref{Examining, , Examining and Setting Variables, emacs,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9497 The GNU Emacs Manual}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9498
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9499 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9500 @node cons & search-fwd Review, search Exercises, defvar, Cutting & Storing Text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9501 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9502 @section Review
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9503
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9504 Here is a brief summary of some recently introduced functions.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9505
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9506 @table @code
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9507 @item car
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9508 @itemx cdr
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9509 @code{car} returns the first element of a list; @code{cdr} returns the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9510 second and subsequent elements of a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9511
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9512 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9513 For example:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9514
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9515 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9516 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9517 (car '(1 2 3 4 5 6 7))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9518 @result{} 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9519 (cdr '(1 2 3 4 5 6 7))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9520 @result{} (2 3 4 5 6 7)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9521 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9522 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9523
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9524 @item cons
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9525 @code{cons} constructs a list by prepending its first argument to its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9526 second argument.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9527
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9528 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9529 For example:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9530
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9531 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9532 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9533 (cons 1 '(2 3 4))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9534 @result{} (1 2 3 4)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9535 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9536 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9537
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9538 @item funcall
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9539 @code{funcall} evaluates its first argument as a function. It passes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9540 its remaining arguments to its first argument.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9541
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9542 @item nthcdr
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9543 Return the result of taking @sc{cdr} `n' times on a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9544 @iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9545 The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9546 @tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9547 $n^{th}$
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9548 @end tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9549 @code{cdr}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9550 @end iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9551 The `rest of the rest', as it were.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9552
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9553 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9554 For example:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9555
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9556 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9557 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9558 (nthcdr 3 '(1 2 3 4 5 6 7))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9559 @result{} (4 5 6 7)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9560 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9561 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9562
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9563 @item setcar
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9564 @itemx setcdr
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9565 @code{setcar} changes the first element of a list; @code{setcdr}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9566 changes the second and subsequent elements of a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9567
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9568 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9569 For example:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9570
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9571 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9572 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9573 (setq triple '(1 2 3))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9574
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9575 (setcar triple '37)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9576
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9577 triple
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9578 @result{} (37 2 3)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9579
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9580 (setcdr triple '("foo" "bar"))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9581
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9582 triple
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9583 @result{} (37 "foo" "bar")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9584 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9585 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9586
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9587 @item progn
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9588 Evaluate each argument in sequence and then return the value of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9589 last.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9590
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9591 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9592 For example:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9593
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9594 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9595 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9596 (progn 1 2 3 4)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9597 @result{} 4
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9598 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9599 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9600
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9601 @item save-restriction
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9602 Record whatever narrowing is in effect in the current buffer, if any,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9603 and restore that narrowing after evaluating the arguments.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9604
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9605 @item search-forward
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9606 Search for a string, and if the string is found, move point. With a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9607 regular expression, use the similar @code{re-search-forward}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9608 (@xref{Regexp Search, , Regular Expression Searches}, for an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9609 explanation of regular expression patterns and searches.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9610
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9611 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9612 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9613 @code{search-forward} and @code{re-search-forward} take four
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9614 arguments:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9615
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9616 @enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9617 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9618 The string or regular expression to search for.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9619
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9620 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9621 Optionally, the limit of the search.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9622
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9623 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9624 Optionally, what to do if the search fails, return @code{nil} or an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9625 error message.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9626
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9627 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9628 Optionally, how many times to repeat the search; if negative, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9629 search goes backwards.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9630 @end enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9631
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9632 @item kill-region
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9633 @itemx delete-and-extract-region
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9634 @itemx copy-region-as-kill
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9635
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9636 @code{kill-region} cuts the text between point and mark from the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9637 buffer and stores that text in the kill ring, so you can get it back
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9638 by yanking.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9639
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9640 @code{copy-region-as-kill} copies the text between point and mark into
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9641 the kill ring, from which you can get it by yanking. The function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9642 does not cut or remove the text from the buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9643 @end table
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9644
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9645 @code{delete-and-extract-region} removes the text between point and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9646 mark from the buffer and throws it away. You cannot get it back.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9647 (This is not an interactive command.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9648
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9649 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9650 @node search Exercises, , cons & search-fwd Review, Cutting & Storing Text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9651 @section Searching Exercises
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9652
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9653 @itemize @bullet
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9654 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9655 Write an interactive function that searches for a string. If the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9656 search finds the string, leave point after it and display a message
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9657 that says ``Found!''. (Do not use @code{search-forward} for the name
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9658 of this function; if you do, you will overwrite the existing version of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9659 @code{search-forward} that comes with Emacs. Use a name such as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9660 @code{test-search} instead.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9661
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9662 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9663 Write a function that prints the third element of the kill ring in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9664 echo area, if any; if the kill ring does not contain a third element,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9665 print an appropriate message.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9666 @end itemize
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9667
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9668 @node List Implementation, Yanking, Cutting & Storing Text, Top
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9669 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9670 @chapter How Lists are Implemented
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9671 @cindex Lists in a computer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9672
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9673 In Lisp, atoms are recorded in a straightforward fashion; if the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9674 implementation is not straightforward in practice, it is, nonetheless,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9675 straightforward in theory. The atom @samp{rose}, for example, is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9676 recorded as the four contiguous letters @samp{r}, @samp{o}, @samp{s},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9677 @samp{e}. A list, on the other hand, is kept differently. The mechanism
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9678 is equally simple, but it takes a moment to get used to the idea. A
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9679 list is kept using a series of pairs of pointers. In the series, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9680 first pointer in each pair points to an atom or to another list, and the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9681 second pointer in each pair points to the next pair, or to the symbol
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9682 @code{nil}, which marks the end of the list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9683
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9684 A pointer itself is quite simply the electronic address of what is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9685 pointed to. Hence, a list is kept as a series of electronic addresses.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9686
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9687 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9688 * Lists diagrammed::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9689 * Symbols as Chest:: Exploring a powerful metaphor.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9690 * List Exercise::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9691 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9692
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9693 @node Lists diagrammed, Symbols as Chest, List Implementation, List Implementation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9694 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9695 @unnumberedsec Lists diagrammed
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9696 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9697
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9698 For example, the list @code{(rose violet buttercup)} has three elements,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9699 @samp{rose}, @samp{violet}, and @samp{buttercup}. In the computer, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9700 electronic address of @samp{rose} is recorded in a segment of computer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9701 memory along with the address that gives the electronic address of where
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9702 the atom @samp{violet} is located; and that address (the one that tells
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9703 where @samp{violet} is located) is kept along with an address that tells
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9704 where the address for the atom @samp{buttercup} is located.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9705
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9706 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9707 This sounds more complicated than it is and is easier seen in a diagram:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9708
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9709 @c clear print-postscript-figures
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9710 @c !!! cons-cell-diagram #1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9711 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9712 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9713 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9714 ___ ___ ___ ___ ___ ___
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9715 |___|___|--> |___|___|--> |___|___|--> nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9716 | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9717 | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9718 --> rose --> violet --> buttercup
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9719 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9720 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9721 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9722 @ifset print-postscript-figures
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9723 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9724 @tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9725 @center @image{cons-1}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9726 %%%% old method of including an image
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9727 % \input /usr/local/lib/tex/inputs/psfig.tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9728 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-1.eps}}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9729 % \catcode`\@=0 %
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9730 @end tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9731 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9732 @end ifset
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9733 @ifclear print-postscript-figures
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9734 @iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9735 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9736 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9737 ___ ___ ___ ___ ___ ___
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9738 |___|___|--> |___|___|--> |___|___|--> nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9739 | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9740 | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9741 --> rose --> violet --> buttercup
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9742 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9743 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9744 @end iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9745 @end ifclear
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9746
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9747 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9748 In the diagram, each box represents a word of computer memory that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9749 holds a Lisp object, usually in the form of a memory address. The boxes,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9750 i.e.@: the addresses, are in pairs. Each arrow points to what the address
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9751 is the address of, either an atom or another pair of addresses. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9752 first box is the electronic address of @samp{rose} and the arrow points
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9753 to @samp{rose}; the second box is the address of the next pair of boxes,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9754 the first part of which is the address of @samp{violet} and the second
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9755 part of which is the address of the next pair. The very last box
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9756 points to the symbol @code{nil}, which marks the end of the list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9757
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9758 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9759 When a variable is set to a list with a function such as @code{setq},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9760 it stores the address of the first box in the variable. Thus,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9761 evaluation of the expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9762
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9763 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9764 (setq bouquet '(rose violet buttercup))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9765 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9766
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9767 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9768 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9769 creates a situation like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9770
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9771 @c cons-cell-diagram #2
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9772 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9773 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9774 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9775 bouquet
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9776 |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9777 | ___ ___ ___ ___ ___ ___
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9778 --> |___|___|--> |___|___|--> |___|___|--> nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9779 | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9780 | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9781 --> rose --> violet --> buttercup
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9782 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9783 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9784 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9785 @ifset print-postscript-figures
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9786 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9787 @tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9788 @center @image{cons-2}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9789 %%%% old method of including an image
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9790 % \input /usr/local/lib/tex/inputs/psfig.tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9791 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2.eps}}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9792 % \catcode`\@=0 %
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9793 @end tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9794 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9795 @end ifset
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9796 @ifclear print-postscript-figures
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9797 @iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9798 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9799 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9800 bouquet
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9801 |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9802 | ___ ___ ___ ___ ___ ___
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9803 --> |___|___|--> |___|___|--> |___|___|--> nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9804 | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9805 | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9806 --> rose --> violet --> buttercup
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9807 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9808 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9809 @end iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9810 @end ifclear
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9811
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9812 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9813 In this example, the symbol @code{bouquet} holds the address of the first
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9814 pair of boxes.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9815
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9816 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9817 This same list can be illustrated in a different sort of box notation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9818 like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9819
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9820 @c cons-cell-diagram #2a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9821 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9822 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9823 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9824 bouquet
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9825 |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9826 | -------------- --------------- ----------------
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9827 | | car | cdr | | car | cdr | | car | cdr |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9828 -->| rose | o------->| violet | o------->| butter- | nil |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9829 | | | | | | | cup | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9830 -------------- --------------- ----------------
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9831 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9832 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9833 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9834 @ifset print-postscript-figures
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9835 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9836 @tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9837 @center @image{cons-2a}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9838 %%%% old method of including an image
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9839 % \input /usr/local/lib/tex/inputs/psfig.tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9840 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2a.eps}}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9841 % \catcode`\@=0 %
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9842 @end tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9843 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9844 @end ifset
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9845 @ifclear print-postscript-figures
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9846 @iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9847 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9848 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9849 bouquet
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9850 |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9851 | -------------- --------------- ----------------
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9852 | | car | cdr | | car | cdr | | car | cdr |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9853 -->| rose | o------->| violet | o------->| butter- | nil |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9854 | | | | | | | cup | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9855 -------------- --------------- ----------------
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9856 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9857 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9858 @end iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9859 @end ifclear
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9860
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9861 (Symbols consist of more than pairs of addresses, but the structure of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9862 a symbol is made up of addresses. Indeed, the symbol @code{bouquet}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9863 consists of a group of address-boxes, one of which is the address of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9864 the printed word @samp{bouquet}, a second of which is the address of a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9865 function definition attached to the symbol, if any, a third of which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9866 is the address of the first pair of address-boxes for the list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9867 @code{(rose violet buttercup)}, and so on. Here we are showing that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9868 the symbol's third address-box points to the first pair of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9869 address-boxes for the list.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9870
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9871 If a symbol is set to the @sc{cdr} of a list, the list itself is not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9872 changed; the symbol simply has an address further down the list. (In
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9873 the jargon, @sc{car} and @sc{cdr} are `non-destructive'.) Thus,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9874 evaluation of the following expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9875
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9876 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9877 (setq flowers (cdr bouquet))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9878 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9879
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9880 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9881 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9882 produces this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9883
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9884 @c cons-cell-diagram #3
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9885 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9886 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9887 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9888 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9889 bouquet flowers
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9890 | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9891 | ___ ___ | ___ ___ ___ ___
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9892 --> | | | --> | | | | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9893 |___|___|----> |___|___|--> |___|___|--> nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9894 | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9895 | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9896 --> rose --> violet --> buttercup
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9897 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9898 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9899 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9900 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9901 @ifset print-postscript-figures
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9902 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9903 @tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9904 @center @image{cons-3}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9905 %%%% old method of including an image
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9906 % \input /usr/local/lib/tex/inputs/psfig.tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9907 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-3.eps}}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9908 % \catcode`\@=0 %
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9909 @end tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9910 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9911 @end ifset
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9912 @ifclear print-postscript-figures
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9913 @iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9914 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9915 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9916 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9917 bouquet flowers
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9918 | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9919 | ___ ___ | ___ ___ ___ ___
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9920 --> | | | --> | | | | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9921 |___|___|----> |___|___|--> |___|___|--> nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9922 | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9923 | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9924 --> rose --> violet --> buttercup
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9925 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9926 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9927 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9928 @end iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9929 @end ifclear
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9930
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9931 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9932 The value of @code{flowers} is @code{(violet buttercup)}, which is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9933 to say, the symbol @code{flowers} holds the address of the pair of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9934 address-boxes, the first of which holds the address of @code{violet},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9935 and the second of which holds the address of @code{buttercup}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9936
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9937 A pair of address-boxes is called a @dfn{cons cell} or @dfn{dotted
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9938 pair}. @xref{Cons Cell Type, , Cons Cell and List Types, elisp, The GNU Emacs Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9939 Reference Manual}, and @ref{Dotted Pair Notation, , Dotted Pair
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9940 Notation, elisp, The GNU Emacs Lisp Reference Manual}, for more
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9941 information about cons cells and dotted pairs.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9942
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9943 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9944 The function @code{cons} adds a new pair of addresses to the front of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9945 a series of addresses like that shown above. For example, evaluating
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9946 the expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9947
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9948 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9949 (setq bouquet (cons 'lily bouquet))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9950 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9951
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9952 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9953 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9954 produces:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9955
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9956 @c cons-cell-diagram #4
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9957 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9958 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9959 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9960 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9961 bouquet flowers
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9962 | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9963 | ___ ___ ___ ___ | ___ ___ ___ ___
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9964 --> | | | | | | --> | | | | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9965 |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9966 | | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9967 | | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9968 --> lily --> rose --> violet --> buttercup
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9969 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9970 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9971 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9972 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9973 @ifset print-postscript-figures
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9974 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9975 @tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9976 @center @image{cons-4}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9977 %%%% old method of including an image
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9978 % \input /usr/local/lib/tex/inputs/psfig.tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9979 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-4.eps}}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9980 % \catcode`\@=0 %
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9981 @end tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9982 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9983 @end ifset
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9984 @ifclear print-postscript-figures
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9985 @iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9986 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9987 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9988 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9989 bouquet flowers
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9990 | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9991 | ___ ___ ___ ___ | ___ ___ ___ ___
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9992 --> | | | | | | --> | | | | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9993 |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9994 | | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9995 | | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9996 --> lily --> rose --> violet --> buttercup
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9997 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9998 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9999 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10000 @end iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10001 @end ifclear
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10002
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10003 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10004 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10005 However, this does not change the value of the symbol
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10006 @code{flowers}, as you can see by evaluating the following,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10007
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10008 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10009 (eq (cdr (cdr bouquet)) flowers)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10010 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10011
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10012 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10013 which returns @code{t} for true.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10014
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10015 Until it is reset, @code{flowers} still has the value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10016 @code{(violet buttercup)}; that is, it has the address of the cons
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10017 cell whose first address is of @code{violet}. Also, this does not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10018 alter any of the pre-existing cons cells; they are all still there.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10019
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10020 Thus, in Lisp, to get the @sc{cdr} of a list, you just get the address
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10021 of the next cons cell in the series; to get the @sc{car} of a list,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10022 you get the address of the first element of the list; to @code{cons} a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10023 new element on a list, you add a new cons cell to the front of the list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10024 That is all there is to it! The underlying structure of Lisp is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10025 brilliantly simple!
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10026
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10027 And what does the last address in a series of cons cells refer to? It
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10028 is the address of the empty list, of @code{nil}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10029
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10030 In summary, when a Lisp variable is set to a value, it is provided with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10031 the address of the list to which the variable refers.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10032
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10033 @node Symbols as Chest, List Exercise, Lists diagrammed, List Implementation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10034 @section Symbols as a Chest of Drawers
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10035 @cindex Symbols as a Chest of Drawers
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10036 @cindex Chest of Drawers, metaphor for a symbol
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10037 @cindex Drawers, Chest of, metaphor for a symbol
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10038
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10039 In an earlier section, I suggested that you might imagine a symbol as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10040 being a chest of drawers. The function definition is put in one
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10041 drawer, the value in another, and so on. What is put in the drawer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10042 holding the value can be changed without affecting the contents of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10043 drawer holding the function definition, and vice-verse.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10044
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10045 Actually, what is put in each drawer is the address of the value or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10046 function definition. It is as if you found an old chest in the attic,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10047 and in one of its drawers you found a map giving you directions to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10048 where the buried treasure lies.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10049
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10050 (In addition to its name, symbol definition, and variable value, a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10051 symbol has a `drawer' for a @dfn{property list} which can be used to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10052 record other information. Property lists are not discussed here; see
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10053 @ref{Property Lists, , Property Lists, elisp, The GNU Emacs Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10054 Reference Manual}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10055
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10056 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10057 Here is a fanciful representation:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10058
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10059 @c chest-of-drawers diagram
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10060 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10061 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10062 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10063 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10064 Chest of Drawers Contents of Drawers
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10065
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10066 __ o0O0o __
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10067 / \
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10068 ---------------------
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10069 | directions to | [map to]
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10070 | symbol name | bouquet
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10071 | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10072 +---------------------+
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10073 | directions to |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10074 | symbol definition | [none]
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10075 | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10076 +---------------------+
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10077 | directions to | [map to]
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10078 | variable value | (rose violet buttercup)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10079 | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10080 +---------------------+
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10081 | directions to |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10082 | property list | [not described here]
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10083 | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10084 +---------------------+
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10085 |/ \|
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10086 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10087 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10088 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10089 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10090 @ifset print-postscript-figures
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10091 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10092 @tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10093 @center @image{drawers}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10094 %%%% old method of including an image
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10095 % \input /usr/local/lib/tex/inputs/psfig.tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10096 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/drawers.eps}}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10097 % \catcode`\@=0 %
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10098 @end tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10099 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10100 @end ifset
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10101 @ifclear print-postscript-figures
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10102 @iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10103 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10104 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10105 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10106 Chest of Drawers Contents of Drawers
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10107
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10108 __ o0O0o __
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10109 / \
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10110 ---------------------
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10111 | directions to | [map to]
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10112 | symbol name | bouquet
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10113 | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10114 +---------------------+
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10115 | directions to |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10116 | symbol definition | [none]
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10117 | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10118 +---------------------+
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10119 | directions to | [map to]
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10120 | variable value | (rose violet buttercup)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10121 | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10122 +---------------------+
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10123 | directions to |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10124 | property list | [not described here]
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10125 | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10126 +---------------------+
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10127 |/ \|
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10128 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10129 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10130 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10131 @end iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10132 @end ifclear
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10133
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10134 @node List Exercise, , Symbols as Chest, List Implementation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10135 @section Exercise
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10136
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10137 Set @code{flowers} to @code{violet} and @code{buttercup}. Cons two
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10138 more flowers on to this list and set this new list to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10139 @code{more-flowers}. Set the @sc{car} of @code{flowers} to a fish.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10140 What does the @code{more-flowers} list now contain?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10141
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10142 @node Yanking, Loops & Recursion, List Implementation, Top
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10143 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10144 @chapter Yanking Text Back
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10145 @findex yank
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10146 @cindex Text retrieval
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10147 @cindex Retrieving text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10148 @cindex Pasting text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10149
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10150 Whenever you cut text out of a buffer with a `kill' command in GNU Emacs,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10151 you can bring it back with a `yank' command. The text that is cut out of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10152 the buffer is put in the kill ring and the yank commands insert the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10153 appropriate contents of the kill ring back into a buffer (not necessarily
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10154 the original buffer).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10155
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10156 A simple @kbd{C-y} (@code{yank}) command inserts the first item from
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10157 the kill ring into the current buffer. If the @kbd{C-y} command is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10158 followed immediately by @kbd{M-y}, the first element is replaced by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10159 the second element. Successive @kbd{M-y} commands replace the second
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10160 element with the third, fourth, or fifth element, and so on. When the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10161 last element in the kill ring is reached, it is replaced by the first
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10162 element and the cycle is repeated. (Thus the kill ring is called a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10163 `ring' rather than just a `list'. However, the actual data structure
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10164 that holds the text is a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10165 @xref{Kill Ring, , Handling the Kill Ring}, for the details of how the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10166 list is handled as a ring.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10167
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10168 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10169 * Kill Ring Overview::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10170 * kill-ring-yank-pointer:: The kill ring is a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10171 * yank nthcdr Exercises:: The @code{kill-ring-yank-pointer} variable.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10172 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10173
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10174 @node Kill Ring Overview, kill-ring-yank-pointer, Yanking, Yanking
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10175 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10176 @section Kill Ring Overview
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10177 @cindex Kill ring overview
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10178
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10179 The kill ring is a list of textual strings. This is what it looks like:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10180
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10181 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10182 ("some text" "a different piece of text" "yet more text")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10183 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10184
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10185 If this were the contents of my kill ring and I pressed @kbd{C-y}, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10186 string of characters saying @samp{some text} would be inserted in this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10187 buffer where my cursor is located.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10188
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10189 The @code{yank} command is also used for duplicating text by copying it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10190 The copied text is not cut from the buffer, but a copy of it is put on the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10191 kill ring and is inserted by yanking it back.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10192
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10193 Three functions are used for bringing text back from the kill ring:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10194 @code{yank}, which is usually bound to @kbd{C-y}; @code{yank-pop},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10195 which is usually bound to @kbd{M-y}; and @code{rotate-yank-pointer},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10196 which is used by the two other functions.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10197
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10198 These functions refer to the kill ring through a variable called the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10199 @code{kill-ring-yank-pointer}. Indeed, the insertion code for both the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10200 @code{yank} and @code{yank-pop} functions is:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10201
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10202 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10203 (insert (car kill-ring-yank-pointer))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10204 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10205
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10206 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10207 (Well, no more. In GNU Emacs 22, the function has been replaced by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10208 @code{insert-for-yank} which calls @code{insert-for-yank-1}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10209 repetitively for each @code{yank-handler} segment. In turn,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10210 @code{insert-for-yank-1} strips text properties from the inserted text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10211 according to @code{yank-excluded-properties}. Otherwise, it is just
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10212 like @code{insert}. We will stick with plain @code{insert} since it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10213 is easier to understand.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10214
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10215 To begin to understand how @code{yank} and @code{yank-pop} work, it is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10216 first necessary to look at the @code{kill-ring-yank-pointer} variable.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10217
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10218 @node kill-ring-yank-pointer, yank nthcdr Exercises, Kill Ring Overview, Yanking
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10219 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10220 @section The @code{kill-ring-yank-pointer} Variable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10221
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10222 @code{kill-ring-yank-pointer} is a variable, just as @code{kill-ring} is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10223 a variable. It points to something by being bound to the value of what
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10224 it points to, like any other Lisp variable.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10225
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10226 @need 1000
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10227 Thus, if the value of the kill ring is:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10228
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10229 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10230 ("some text" "a different piece of text" "yet more text")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10231 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10232
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10233 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10234 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10235 and the @code{kill-ring-yank-pointer} points to the second clause, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10236 value of @code{kill-ring-yank-pointer} is:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10237
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10238 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10239 ("a different piece of text" "yet more text")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10240 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10241
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10242 As explained in the previous chapter (@pxref{List Implementation}), the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10243 computer does not keep two different copies of the text being pointed to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10244 by both the @code{kill-ring} and the @code{kill-ring-yank-pointer}. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10245 words ``a different piece of text'' and ``yet more text'' are not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10246 duplicated. Instead, the two Lisp variables point to the same pieces of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10247 text. Here is a diagram:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10248
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10249 @c cons-cell-diagram #5
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10250 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10251 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10252 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10253 kill-ring kill-ring-yank-pointer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10254 | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10255 | ___ ___ | ___ ___ ___ ___
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10256 ---> | | | --> | | | | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10257 |___|___|----> |___|___|--> |___|___|--> nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10258 | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10259 | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10260 | | --> "yet more text"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10261 | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10262 | --> "a different piece of text"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10263 |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10264 --> "some text"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10265 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10266 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10267 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10268 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10269 @ifset print-postscript-figures
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10270 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10271 @tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10272 @center @image{cons-5}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10273 %%%% old method of including an image
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10274 % \input /usr/local/lib/tex/inputs/psfig.tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10275 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-5.eps}}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10276 % \catcode`\@=0 %
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10277 @end tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10278 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10279 @end ifset
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10280 @ifclear print-postscript-figures
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10281 @iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10282 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10283 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10284 kill-ring kill-ring-yank-pointer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10285 | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10286 | ___ ___ | ___ ___ ___ ___
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10287 ---> | | | --> | | | | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10288 |___|___|----> |___|___|--> |___|___|--> nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10289 | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10290 | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10291 | | --> "yet more text"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10292 | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10293 | --> "a different piece of text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10294 |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10295 --> "some text"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10296 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10297 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10298 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10299 @end iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10300 @end ifclear
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10301
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10302 Both the variable @code{kill-ring} and the variable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10303 @code{kill-ring-yank-pointer} are pointers. But the kill ring itself is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10304 usually described as if it were actually what it is composed of. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10305 @code{kill-ring} is spoken of as if it were the list rather than that it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10306 points to the list. Conversely, the @code{kill-ring-yank-pointer} is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10307 spoken of as pointing to a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10308
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10309 These two ways of talking about the same thing sound confusing at first but
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10310 make sense on reflection. The kill ring is generally thought of as the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10311 complete structure of data that holds the information of what has recently
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10312 been cut out of the Emacs buffers. The @code{kill-ring-yank-pointer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10313 on the other hand, serves to indicate---that is, to `point to'---that part
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10314 of the kill ring of which the first element (the @sc{car}) will be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10315 inserted.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10316
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10317 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10318 In GNU Emacs 22, the @code{kill-new} function calls
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10319
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10320 @code{(setq kill-ring-yank-pointer kill-ring)}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10321
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10322 (defun rotate-yank-pointer (arg)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10323 "Rotate the yanking point in the kill ring.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10324 With argument, rotate that many kills forward (or backward, if negative)."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10325 (interactive "p")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10326 (current-kill arg))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10327
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10328 (defun current-kill (n &optional do-not-move)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10329 "Rotate the yanking point by N places, and then return that kill.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10330 If N is zero, `interprogram-paste-function' is set, and calling it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10331 returns a string, then that string is added to the front of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10332 kill ring and returned as the latest kill.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10333 If optional arg DO-NOT-MOVE is non-nil, then don't actually move the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10334 yanking point; just return the Nth kill forward."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10335 (let ((interprogram-paste (and (= n 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10336 interprogram-paste-function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10337 (funcall interprogram-paste-function))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10338 (if interprogram-paste
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10339 (progn
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10340 ;; Disable the interprogram cut function when we add the new
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10341 ;; text to the kill ring, so Emacs doesn't try to own the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10342 ;; selection, with identical text.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10343 (let ((interprogram-cut-function nil))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10344 (kill-new interprogram-paste))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10345 interprogram-paste)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10346 (or kill-ring (error "Kill ring is empty"))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10347 (let ((ARGth-kill-element
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10348 (nthcdr (mod (- n (length kill-ring-yank-pointer))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10349 (length kill-ring))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10350 kill-ring)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10351 (or do-not-move
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10352 (setq kill-ring-yank-pointer ARGth-kill-element))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10353 (car ARGth-kill-element)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10354
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10355 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10356
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10357 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10358 @node yank nthcdr Exercises, , kill-ring-yank-pointer, Yanking
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10359 @section Exercises with @code{yank} and @code{nthcdr}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10360
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10361 @itemize @bullet
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10362 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10363 Using @kbd{C-h v} (@code{describe-variable}), look at the value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10364 your kill ring. Add several items to your kill ring; look at its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10365 value again. Using @kbd{M-y} (@code{yank-pop)}, move all the way
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10366 around the kill ring. How many items were in your kill ring? Find
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10367 the value of @code{kill-ring-max}. Was your kill ring full, or could
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10368 you have kept more blocks of text within it?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10369
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10370 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10371 Using @code{nthcdr} and @code{car}, construct a series of expressions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10372 to return the first, second, third, and fourth elements of a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10373 @end itemize
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10374
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10375 @node Loops & Recursion, Regexp Search, Yanking, Top
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10376 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10377 @chapter Loops and Recursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10378 @cindex Loops and recursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10379 @cindex Recursion and loops
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10380 @cindex Repetition (loops)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10381
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10382 Emacs Lisp has two primary ways to cause an expression, or a series of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10383 expressions, to be evaluated repeatedly: one uses a @code{while}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10384 loop, and the other uses @dfn{recursion}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10385
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10386 Repetition can be very valuable. For example, to move forward four
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10387 sentences, you need only write a program that will move forward one
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10388 sentence and then repeat the process four times. Since a computer does
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10389 not get bored or tired, such repetitive action does not have the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10390 deleterious effects that excessive or the wrong kinds of repetition can
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10391 have on humans.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10392
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10393 People mostly write Emacs Lisp functions using @code{while} loops and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10394 their kin; but you can use recursion, which provides a very powerful
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10395 way to think about and then to solve problems@footnote{You can write
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10396 recursive functions to be frugal or wasteful of mental or computer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10397 resources; as it happens, methods that people find easy---that are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10398 frugal of `mental resources'---sometimes use considerable computer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10399 resources. Emacs was designed to run on machines that we now consider
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10400 limited and its default settings are conservative. You may want to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10401 increase the values of @code{max-specpdl-size} and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10402 @code{max-lisp-eval-depth}. In my @file{.emacs} file, I set them to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10403 15 and 30 times their default value.}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10404
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10405 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10406 * while:: Causing a stretch of code to repeat.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10407 * dolist dotimes::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10408 * Recursion:: Causing a function to call itself.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10409 * Looping exercise::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10410 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10411
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10412 @node while, dolist dotimes, Loops & Recursion, Loops & Recursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10413 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10414 @section @code{while}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10415 @cindex Loops
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10416 @findex while
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10417
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10418 The @code{while} special form tests whether the value returned by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10419 evaluating its first argument is true or false. This is similar to what
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10420 the Lisp interpreter does with an @code{if}; what the interpreter does
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10421 next, however, is different.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10422
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10423 In a @code{while} expression, if the value returned by evaluating the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10424 first argument is false, the Lisp interpreter skips the rest of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10425 expression (the @dfn{body} of the expression) and does not evaluate it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10426 However, if the value is true, the Lisp interpreter evaluates the body
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10427 of the expression and then again tests whether the first argument to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10428 @code{while} is true or false. If the value returned by evaluating the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10429 first argument is again true, the Lisp interpreter again evaluates the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10430 body of the expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10431
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10432 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10433 The template for a @code{while} expression looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10434
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10435 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10436 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10437 (while @var{true-or-false-test}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10438 @var{body}@dots{})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10439 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10440 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10441
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10442 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10443 * Looping with while:: Repeat so long as test returns true.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10444 * Loop Example:: A @code{while} loop that uses a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10445 * print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10446 * Incrementing Loop:: A loop with an incrementing counter.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10447 * Incrementing Loop Details::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10448 * Decrementing Loop:: A loop with a decrementing counter.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10449 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10450
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10451 @node Looping with while, Loop Example, while, while
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10452 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10453 @unnumberedsubsec Looping with @code{while}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10454 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10455
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10456 So long as the true-or-false-test of the @code{while} expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10457 returns a true value when it is evaluated, the body is repeatedly
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10458 evaluated. This process is called a loop since the Lisp interpreter
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10459 repeats the same thing again and again, like an airplane doing a loop.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10460 When the result of evaluating the true-or-false-test is false, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10461 Lisp interpreter does not evaluate the rest of the @code{while}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10462 expression and `exits the loop'.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10463
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10464 Clearly, if the value returned by evaluating the first argument to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10465 @code{while} is always true, the body following will be evaluated
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10466 again and again @dots{} and again @dots{} forever. Conversely, if the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10467 value returned is never true, the expressions in the body will never
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10468 be evaluated. The craft of writing a @code{while} loop consists of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10469 choosing a mechanism such that the true-or-false-test returns true
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10470 just the number of times that you want the subsequent expressions to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10471 be evaluated, and then have the test return false.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10472
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10473 The value returned by evaluating a @code{while} is the value of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10474 true-or-false-test. An interesting consequence of this is that a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10475 @code{while} loop that evaluates without error will return @code{nil}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10476 or false regardless of whether it has looped 1 or 100 times or none at
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10477 all. A @code{while} expression that evaluates successfully never
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10478 returns a true value! What this means is that @code{while} is always
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10479 evaluated for its side effects, which is to say, the consequences of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10480 evaluating the expressions within the body of the @code{while} loop.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10481 This makes sense. It is not the mere act of looping that is desired,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10482 but the consequences of what happens when the expressions in the loop
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10483 are repeatedly evaluated.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10484
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10485 @node Loop Example, print-elements-of-list, Looping with while, while
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10486 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10487 @subsection A @code{while} Loop and a List
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10488
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10489 A common way to control a @code{while} loop is to test whether a list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10490 has any elements. If it does, the loop is repeated; but if it does not,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10491 the repetition is ended. Since this is an important technique, we will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10492 create a short example to illustrate it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10493
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10494 A simple way to test whether a list has elements is to evaluate the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10495 list: if it has no elements, it is an empty list and will return the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10496 empty list, @code{()}, which is a synonym for @code{nil} or false. On
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10497 the other hand, a list with elements will return those elements when it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10498 is evaluated. Since Emacs Lisp considers as true any value that is not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10499 @code{nil}, a list that returns elements will test true in a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10500 @code{while} loop.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10501
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10502 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10503 For example, you can set the variable @code{empty-list} to @code{nil} by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10504 evaluating the following @code{setq} expression:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10505
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10506 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10507 (setq empty-list ())
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10508 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10509
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10510 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10511 After evaluating the @code{setq} expression, you can evaluate the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10512 variable @code{empty-list} in the usual way, by placing the cursor after
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10513 the symbol and typing @kbd{C-x C-e}; @code{nil} will appear in your
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10514 echo area:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10515
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10516 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10517 empty-list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10518 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10519
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10520 On the other hand, if you set a variable to be a list with elements, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10521 list will appear when you evaluate the variable, as you can see by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10522 evaluating the following two expressions:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10523
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10524 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10525 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10526 (setq animals '(gazelle giraffe lion tiger))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10527
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10528 animals
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10529 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10530 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10531
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10532 Thus, to create a @code{while} loop that tests whether there are any
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10533 items in the list @code{animals}, the first part of the loop will be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10534 written like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10535
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10536 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10537 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10538 (while animals
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10539 @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10540 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10541 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10542
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10543 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10544 When the @code{while} tests its first argument, the variable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10545 @code{animals} is evaluated. It returns a list. So long as the list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10546 has elements, the @code{while} considers the results of the test to be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10547 true; but when the list is empty, it considers the results of the test
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10548 to be false.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10549
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10550 To prevent the @code{while} loop from running forever, some mechanism
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10551 needs to be provided to empty the list eventually. An oft-used
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10552 technique is to have one of the subsequent forms in the @code{while}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10553 expression set the value of the list to be the @sc{cdr} of the list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10554 Each time the @code{cdr} function is evaluated, the list will be made
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10555 shorter, until eventually only the empty list will be left. At this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10556 point, the test of the @code{while} loop will return false, and the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10557 arguments to the @code{while} will no longer be evaluated.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10558
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10559 For example, the list of animals bound to the variable @code{animals}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10560 can be set to be the @sc{cdr} of the original list with the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10561 following expression:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10562
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10563 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10564 (setq animals (cdr animals))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10565 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10566
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10567 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10568 If you have evaluated the previous expressions and then evaluate this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10569 expression, you will see @code{(giraffe lion tiger)} appear in the echo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10570 area. If you evaluate the expression again, @code{(lion tiger)} will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10571 appear in the echo area. If you evaluate it again and yet again,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10572 @code{(tiger)} appears and then the empty list, shown by @code{nil}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10573
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10574 A template for a @code{while} loop that uses the @code{cdr} function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10575 repeatedly to cause the true-or-false-test eventually to test false
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10576 looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10577
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10578 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10579 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10580 (while @var{test-whether-list-is-empty}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10581 @var{body}@dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10582 @var{set-list-to-cdr-of-list})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10583 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10584 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10585
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10586 This test and use of @code{cdr} can be put together in a function that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10587 goes through a list and prints each element of the list on a line of its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10588 own.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10589
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10590 @node print-elements-of-list, Incrementing Loop, Loop Example, while
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10591 @subsection An Example: @code{print-elements-of-list}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10592 @findex print-elements-of-list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10593
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10594 The @code{print-elements-of-list} function illustrates a @code{while}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10595 loop with a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10596
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10597 @cindex @file{*scratch*} buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10598 The function requires several lines for its output. If you are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10599 reading this in a recent instance of GNU Emacs,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10600 @c GNU Emacs 21, GNU Emacs 22, or a later version,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10601 you can evaluate the following expression inside of Info, as usual.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10602
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10603 If you are using an earlier version of Emacs, you need to copy the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10604 necessary expressions to your @file{*scratch*} buffer and evaluate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10605 them there. This is because the echo area had only one line in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10606 earlier versions.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10607
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10608 You can copy the expressions by marking the beginning of the region
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10609 with @kbd{C-@key{SPC}} (@code{set-mark-command}), moving the cursor to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10610 the end of the region and then copying the region using @kbd{M-w}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10611 (@code{kill-ring-save}, which calls @code{copy-region-as-kill} and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10612 then provides visual feedback). In the @file{*scratch*}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10613 buffer, you can yank the expressions back by typing @kbd{C-y}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10614 (@code{yank}).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10615
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10616 After you have copied the expressions to the @file{*scratch*} buffer,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10617 evaluate each expression in turn. Be sure to evaluate the last
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10618 expression, @code{(print-elements-of-list animals)}, by typing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10619 @kbd{C-u C-x C-e}, that is, by giving an argument to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10620 @code{eval-last-sexp}. This will cause the result of the evaluation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10621 to be printed in the @file{*scratch*} buffer instead of being printed
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10622 in the echo area. (Otherwise you will see something like this in your
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10623 echo area: @code{^Jgazelle^J^Jgiraffe^J^Jlion^J^Jtiger^Jnil}, in which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10624 each @samp{^J} stands for a `newline'.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10625
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10626 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10627 In a recent instance of GNU Emacs, you can evaluate these expressions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10628 directly in the Info buffer, and the echo area will grow to show the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10629 results.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10630
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10631 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10632 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10633 (setq animals '(gazelle giraffe lion tiger))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10634
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10635 (defun print-elements-of-list (list)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10636 "Print each element of LIST on a line of its own."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10637 (while list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10638 (print (car list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10639 (setq list (cdr list))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10640
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10641 (print-elements-of-list animals)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10642 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10643 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10644
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10645 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10646 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10647 When you evaluate the three expressions in sequence, you will see
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10648 this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10649
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10650 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10651 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10652 gazelle
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10653
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10654 giraffe
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10655
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10656 lion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10657
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10658 tiger
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10659 nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10660 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10661 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10662
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10663 Each element of the list is printed on a line of its own (that is what
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10664 the function @code{print} does) and then the value returned by the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10665 function is printed. Since the last expression in the function is the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10666 @code{while} loop, and since @code{while} loops always return
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10667 @code{nil}, a @code{nil} is printed after the last element of the list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10668
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10669 @node Incrementing Loop, Incrementing Loop Details, print-elements-of-list, while
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10670 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10671 @subsection A Loop with an Incrementing Counter
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10672
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10673 A loop is not useful unless it stops when it ought. Besides
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10674 controlling a loop with a list, a common way of stopping a loop is to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10675 write the first argument as a test that returns false when the correct
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10676 number of repetitions are complete. This means that the loop must
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10677 have a counter---an expression that counts how many times the loop
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10678 repeats itself.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10679
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10680 @node Incrementing Loop Details, Decrementing Loop, Incrementing Loop, while
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10681 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10682 @unnumberedsubsec Details of an Incrementing Loop
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10683 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10684
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10685 The test for a loop with an incrementing counter can be an expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10686 such as @code{(< count desired-number)} which returns @code{t} for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10687 true if the value of @code{count} is less than the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10688 @code{desired-number} of repetitions and @code{nil} for false if the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10689 value of @code{count} is equal to or is greater than the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10690 @code{desired-number}. The expression that increments the count can
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10691 be a simple @code{setq} such as @code{(setq count (1+ count))}, where
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10692 @code{1+} is a built-in function in Emacs Lisp that adds 1 to its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10693 argument. (The expression @w{@code{(1+ count)}} has the same result
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10694 as @w{@code{(+ count 1)}}, but is easier for a human to read.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10695
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10696 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10697 The template for a @code{while} loop controlled by an incrementing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10698 counter looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10699
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10700 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10701 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10702 @var{set-count-to-initial-value}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10703 (while (< count desired-number) ; @r{true-or-false-test}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10704 @var{body}@dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10705 (setq count (1+ count))) ; @r{incrementer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10706 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10707 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10708
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10709 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10710 Note that you need to set the initial value of @code{count}; usually it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10711 is set to 1.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10712
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10713 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10714 * Incrementing Example:: Counting pebbles in a triangle.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10715 * Inc Example parts:: The parts of the function definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10716 * Inc Example altogether:: Putting the function definition together.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10717 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10718
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10719 @node Incrementing Example, Inc Example parts, Incrementing Loop Details, Incrementing Loop Details
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10720 @unnumberedsubsubsec Example with incrementing counter
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10721
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10722 Suppose you are playing on the beach and decide to make a triangle of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10723 pebbles, putting one pebble in the first row, two in the second row,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10724 three in the third row and so on, like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10725
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10726 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10727 @c pebble diagram
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10728 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10729 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10730 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10731 *
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10732 * *
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10733 * * *
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10734 * * * *
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10735 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10736 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10737 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10738 @iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10739 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10740 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10741 @bullet{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10742 @bullet{} @bullet{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10743 @bullet{} @bullet{} @bullet{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10744 @bullet{} @bullet{} @bullet{} @bullet{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10745 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10746 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10747 @end iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10748 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10749
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10750 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10751 (About 2500 years ago, Pythagoras and others developed the beginnings of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10752 number theory by considering questions such as this.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10753
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10754 Suppose you want to know how many pebbles you will need to make a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10755 triangle with 7 rows?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10756
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10757 Clearly, what you need to do is add up the numbers from 1 to 7. There
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10758 are two ways to do this; start with the smallest number, one, and add up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10759 the list in sequence, 1, 2, 3, 4 and so on; or start with the largest
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10760 number and add the list going down: 7, 6, 5, 4 and so on. Because both
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10761 mechanisms illustrate common ways of writing @code{while} loops, we will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10762 create two examples, one counting up and the other counting down. In
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10763 this first example, we will start with 1 and add 2, 3, 4 and so on.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10764
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10765 If you are just adding up a short list of numbers, the easiest way to do
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10766 it is to add up all the numbers at once. However, if you do not know
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10767 ahead of time how many numbers your list will have, or if you want to be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10768 prepared for a very long list, then you need to design your addition so
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10769 that what you do is repeat a simple process many times instead of doing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10770 a more complex process once.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10771
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10772 For example, instead of adding up all the pebbles all at once, what you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10773 can do is add the number of pebbles in the first row, 1, to the number
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10774 in the second row, 2, and then add the total of those two rows to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10775 third row, 3. Then you can add the number in the fourth row, 4, to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10776 total of the first three rows; and so on.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10777
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10778 The critical characteristic of the process is that each repetitive
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10779 action is simple. In this case, at each step we add only two numbers,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10780 the number of pebbles in the row and the total already found. This
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10781 process of adding two numbers is repeated again and again until the last
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10782 row has been added to the total of all the preceding rows. In a more
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10783 complex loop the repetitive action might not be so simple, but it will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10784 be simpler than doing everything all at once.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10785
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10786 @node Inc Example parts, Inc Example altogether, Incrementing Example, Incrementing Loop Details
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10787 @unnumberedsubsubsec The parts of the function definition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10788
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10789 The preceding analysis gives us the bones of our function definition:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10790 first, we will need a variable that we can call @code{total} that will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10791 be the total number of pebbles. This will be the value returned by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10792 the function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10793
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10794 Second, we know that the function will require an argument: this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10795 argument will be the total number of rows in the triangle. It can be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10796 called @code{number-of-rows}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10797
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10798 Finally, we need a variable to use as a counter. We could call this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10799 variable @code{counter}, but a better name is @code{row-number}. That
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10800 is because what the counter does in this function is count rows, and a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10801 program should be written to be as understandable as possible.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10802
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10803 When the Lisp interpreter first starts evaluating the expressions in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10804 function, the value of @code{total} should be set to zero, since we have
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10805 not added anything to it. Then the function should add the number of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10806 pebbles in the first row to the total, and then add the number of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10807 pebbles in the second to the total, and then add the number of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10808 pebbles in the third row to the total, and so on, until there are no
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10809 more rows left to add.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10810
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10811 Both @code{total} and @code{row-number} are used only inside the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10812 function, so they can be declared as local variables with @code{let}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10813 and given initial values. Clearly, the initial value for @code{total}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10814 should be 0. The initial value of @code{row-number} should be 1,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10815 since we start with the first row. This means that the @code{let}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10816 statement will look like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10817
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10818 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10819 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10820 (let ((total 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10821 (row-number 1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10822 @var{body}@dots{})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10823 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10824 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10825
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10826 After the internal variables are declared and bound to their initial
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10827 values, we can begin the @code{while} loop. The expression that serves
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10828 as the test should return a value of @code{t} for true so long as the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10829 @code{row-number} is less than or equal to the @code{number-of-rows}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10830 (If the expression tests true only so long as the row number is less
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10831 than the number of rows in the triangle, the last row will never be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10832 added to the total; hence the row number has to be either less than or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10833 equal to the number of rows.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10834
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10835 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10836 @findex <= @r{(less than or equal)}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10837 Lisp provides the @code{<=} function that returns true if the value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10838 its first argument is less than or equal to the value of its second
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10839 argument and false otherwise. So the expression that the @code{while}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10840 will evaluate as its test should look like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10841
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10842 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10843 (<= row-number number-of-rows)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10844 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10845
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10846 The total number of pebbles can be found by repeatedly adding the number
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10847 of pebbles in a row to the total already found. Since the number of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10848 pebbles in the row is equal to the row number, the total can be found by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10849 adding the row number to the total. (Clearly, in a more complex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10850 situation, the number of pebbles in the row might be related to the row
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10851 number in a more complicated way; if this were the case, the row number
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10852 would be replaced by the appropriate expression.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10853
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10854 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10855 (setq total (+ total row-number))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10856 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10857
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10858 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10859 What this does is set the new value of @code{total} to be equal to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10860 sum of adding the number of pebbles in the row to the previous total.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10861
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10862 After setting the value of @code{total}, the conditions need to be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10863 established for the next repetition of the loop, if there is one. This
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10864 is done by incrementing the value of the @code{row-number} variable,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10865 which serves as a counter. After the @code{row-number} variable has
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10866 been incremented, the true-or-false-test at the beginning of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10867 @code{while} loop tests whether its value is still less than or equal to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10868 the value of the @code{number-of-rows} and if it is, adds the new value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10869 of the @code{row-number} variable to the @code{total} of the previous
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10870 repetition of the loop.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10871
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10872 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10873 The built-in Emacs Lisp function @code{1+} adds 1 to a number, so the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10874 @code{row-number} variable can be incremented with this expression:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10875
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10876 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10877 (setq row-number (1+ row-number))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10878 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10879
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10880 @node Inc Example altogether, , Inc Example parts, Incrementing Loop Details
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10881 @unnumberedsubsubsec Putting the function definition together
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10882
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10883 We have created the parts for the function definition; now we need to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10884 put them together.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10885
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10886 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10887 First, the contents of the @code{while} expression:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10888
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10889 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10890 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10891 (while (<= row-number number-of-rows) ; @r{true-or-false-test}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10892 (setq total (+ total row-number))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10893 (setq row-number (1+ row-number))) ; @r{incrementer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10894 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10895 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10896
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10897 Along with the @code{let} expression varlist, this very nearly
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10898 completes the body of the function definition. However, it requires
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10899 one final element, the need for which is somewhat subtle.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10900
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10901 The final touch is to place the variable @code{total} on a line by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10902 itself after the @code{while} expression. Otherwise, the value returned
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10903 by the whole function is the value of the last expression that is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10904 evaluated in the body of the @code{let}, and this is the value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10905 returned by the @code{while}, which is always @code{nil}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10906
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10907 This may not be evident at first sight. It almost looks as if the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10908 incrementing expression is the last expression of the whole function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10909 But that expression is part of the body of the @code{while}; it is the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10910 last element of the list that starts with the symbol @code{while}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10911 Moreover, the whole of the @code{while} loop is a list within the body
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10912 of the @code{let}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10913
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10914 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10915 In outline, the function will look like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10916
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10917 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10918 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10919 (defun @var{name-of-function} (@var{argument-list})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10920 "@var{documentation}@dots{}"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10921 (let (@var{varlist})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10922 (while (@var{true-or-false-test})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10923 @var{body-of-while}@dots{} )
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10924 @dots{} )) ; @r{Need final expression here.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10925 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10926 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10927
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10928 The result of evaluating the @code{let} is what is going to be returned
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10929 by the @code{defun} since the @code{let} is not embedded within any
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10930 containing list, except for the @code{defun} as a whole. However, if
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10931 the @code{while} is the last element of the @code{let} expression, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10932 function will always return @code{nil}. This is not what we want!
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10933 Instead, what we want is the value of the variable @code{total}. This
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10934 is returned by simply placing the symbol as the last element of the list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10935 starting with @code{let}. It gets evaluated after the preceding
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10936 elements of the list are evaluated, which means it gets evaluated after
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10937 it has been assigned the correct value for the total.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10938
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10939 It may be easier to see this by printing the list starting with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10940 @code{let} all on one line. This format makes it evident that the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10941 @var{varlist} and @code{while} expressions are the second and third
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10942 elements of the list starting with @code{let}, and the @code{total} is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10943 the last element:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10944
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10945 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10946 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10947 (let (@var{varlist}) (while (@var{true-or-false-test}) @var{body-of-while}@dots{} ) total)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10948 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10949 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10950
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10951 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10952 Putting everything together, the @code{triangle} function definition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10953 looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10954
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10955 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10956 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10957 (defun triangle (number-of-rows) ; @r{Version with}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10958 ; @r{ incrementing counter.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10959 "Add up the number of pebbles in a triangle.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10960 The first row has one pebble, the second row two pebbles,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10961 the third row three pebbles, and so on.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10962 The argument is NUMBER-OF-ROWS."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10963 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10964 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10965 (let ((total 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10966 (row-number 1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10967 (while (<= row-number number-of-rows)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10968 (setq total (+ total row-number))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10969 (setq row-number (1+ row-number)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10970 total))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10971 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10972 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10973
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10974 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10975 After you have installed @code{triangle} by evaluating the function, you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10976 can try it out. Here are two examples:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10977
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10978 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10979 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10980 (triangle 4)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10981
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10982 (triangle 7)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10983 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10984 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10985
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10986 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10987 The sum of the first four numbers is 10 and the sum of the first seven
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10988 numbers is 28.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10989
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10990 @node Decrementing Loop, , Incrementing Loop Details, while
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10991 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10992 @subsection Loop with a Decrementing Counter
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10993
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10994 Another common way to write a @code{while} loop is to write the test
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10995 so that it determines whether a counter is greater than zero. So long
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10996 as the counter is greater than zero, the loop is repeated. But when
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10997 the counter is equal to or less than zero, the loop is stopped. For
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10998 this to work, the counter has to start out greater than zero and then
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10999 be made smaller and smaller by a form that is evaluated
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11000 repeatedly.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11001
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11002 The test will be an expression such as @code{(> counter 0)} which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11003 returns @code{t} for true if the value of @code{counter} is greater
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11004 than zero, and @code{nil} for false if the value of @code{counter} is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11005 equal to or less than zero. The expression that makes the number
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11006 smaller and smaller can be a simple @code{setq} such as @code{(setq
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11007 counter (1- counter))}, where @code{1-} is a built-in function in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11008 Emacs Lisp that subtracts 1 from its argument.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11009
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11010 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11011 The template for a decrementing @code{while} loop looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11012
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11013 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11014 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11015 (while (> counter 0) ; @r{true-or-false-test}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11016 @var{body}@dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11017 (setq counter (1- counter))) ; @r{decrementer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11018 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11019 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11020
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11021 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11022 * Decrementing Example:: More pebbles on the beach.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11023 * Dec Example parts:: The parts of the function definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11024 * Dec Example altogether:: Putting the function definition together.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11025 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11026
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11027 @node Decrementing Example, Dec Example parts, Decrementing Loop, Decrementing Loop
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11028 @unnumberedsubsubsec Example with decrementing counter
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11029
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11030 To illustrate a loop with a decrementing counter, we will rewrite the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11031 @code{triangle} function so the counter decreases to zero.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11032
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11033 This is the reverse of the earlier version of the function. In this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11034 case, to find out how many pebbles are needed to make a triangle with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11035 3 rows, add the number of pebbles in the third row, 3, to the number
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11036 in the preceding row, 2, and then add the total of those two rows to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11037 the row that precedes them, which is 1.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11038
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11039 Likewise, to find the number of pebbles in a triangle with 7 rows, add
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11040 the number of pebbles in the seventh row, 7, to the number in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11041 preceding row, which is 6, and then add the total of those two rows to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11042 the row that precedes them, which is 5, and so on. As in the previous
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11043 example, each addition only involves adding two numbers, the total of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11044 the rows already added up and the number of pebbles in the row that is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11045 being added to the total. This process of adding two numbers is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11046 repeated again and again until there are no more pebbles to add.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11047
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11048 We know how many pebbles to start with: the number of pebbles in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11049 last row is equal to the number of rows. If the triangle has seven
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11050 rows, the number of pebbles in the last row is 7. Likewise, we know how
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11051 many pebbles are in the preceding row: it is one less than the number in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11052 the row.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11053
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11054 @node Dec Example parts, Dec Example altogether, Decrementing Example, Decrementing Loop
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11055 @unnumberedsubsubsec The parts of the function definition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11056
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11057 We start with three variables: the total number of rows in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11058 triangle; the number of pebbles in a row; and the total number of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11059 pebbles, which is what we want to calculate. These variables can be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11060 named @code{number-of-rows}, @code{number-of-pebbles-in-row}, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11061 @code{total}, respectively.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11062
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11063 Both @code{total} and @code{number-of-pebbles-in-row} are used only
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11064 inside the function and are declared with @code{let}. The initial
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11065 value of @code{total} should, of course, be zero. However, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11066 initial value of @code{number-of-pebbles-in-row} should be equal to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11067 the number of rows in the triangle, since the addition will start with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11068 the longest row.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11069
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11070 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11071 This means that the beginning of the @code{let} expression will look
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11072 like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11073
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11074 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11075 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11076 (let ((total 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11077 (number-of-pebbles-in-row number-of-rows))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11078 @var{body}@dots{})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11079 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11080 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11081
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11082 The total number of pebbles can be found by repeatedly adding the number
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11083 of pebbles in a row to the total already found, that is, by repeatedly
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11084 evaluating the following expression:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11085
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11086 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11087 (setq total (+ total number-of-pebbles-in-row))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11088 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11089
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11090 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11091 After the @code{number-of-pebbles-in-row} is added to the @code{total},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11092 the @code{number-of-pebbles-in-row} should be decremented by one, since
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11093 the next time the loop repeats, the preceding row will be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11094 added to the total.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11095
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11096 The number of pebbles in a preceding row is one less than the number of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11097 pebbles in a row, so the built-in Emacs Lisp function @code{1-} can be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11098 used to compute the number of pebbles in the preceding row. This can be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11099 done with the following expression:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11100
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11101 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11102 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11103 (setq number-of-pebbles-in-row
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11104 (1- number-of-pebbles-in-row))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11105 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11106 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11107
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11108 Finally, we know that the @code{while} loop should stop making repeated
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11109 additions when there are no pebbles in a row. So the test for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11110 the @code{while} loop is simply:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11111
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11112 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11113 (while (> number-of-pebbles-in-row 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11114 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11115
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11116 @node Dec Example altogether, , Dec Example parts, Decrementing Loop
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11117 @unnumberedsubsubsec Putting the function definition together
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11118
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11119 We can put these expressions together to create a function definition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11120 that works. However, on examination, we find that one of the local
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11121 variables is unneeded!
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11122
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11123 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11124 The function definition looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11125
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11126 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11127 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11128 ;;; @r{First subtractive version.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11129 (defun triangle (number-of-rows)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11130 "Add up the number of pebbles in a triangle."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11131 (let ((total 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11132 (number-of-pebbles-in-row number-of-rows))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11133 (while (> number-of-pebbles-in-row 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11134 (setq total (+ total number-of-pebbles-in-row))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11135 (setq number-of-pebbles-in-row
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11136 (1- number-of-pebbles-in-row)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11137 total))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11138 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11139 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11140
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11141 As written, this function works.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11142
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11143 However, we do not need @code{number-of-pebbles-in-row}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11144
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11145 @cindex Argument as local variable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11146 When the @code{triangle} function is evaluated, the symbol
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11147 @code{number-of-rows} will be bound to a number, giving it an initial
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11148 value. That number can be changed in the body of the function as if
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11149 it were a local variable, without any fear that such a change will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11150 effect the value of the variable outside of the function. This is a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11151 very useful characteristic of Lisp; it means that the variable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11152 @code{number-of-rows} can be used anywhere in the function where
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11153 @code{number-of-pebbles-in-row} is used.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11154
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11155 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11156 Here is a second version of the function written a bit more cleanly:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11157
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11158 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11159 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11160 (defun triangle (number) ; @r{Second version.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11161 "Return sum of numbers 1 through NUMBER inclusive."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11162 (let ((total 0))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11163 (while (> number 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11164 (setq total (+ total number))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11165 (setq number (1- number)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11166 total))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11167 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11168 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11169
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11170 In brief, a properly written @code{while} loop will consist of three parts:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11171
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11172 @enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11173 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11174 A test that will return false after the loop has repeated itself the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11175 correct number of times.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11176
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11177 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11178 An expression the evaluation of which will return the value desired
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11179 after being repeatedly evaluated.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11180
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11181 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11182 An expression to change the value passed to the true-or-false-test so
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11183 that the test returns false after the loop has repeated itself the right
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11184 number of times.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11185 @end enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11186
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11187 @node dolist dotimes, Recursion, while, Loops & Recursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11188 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11189 @section Save your time: @code{dolist} and @code{dotimes}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11190
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11191 In addition to @code{while}, both @code{dolist} and @code{dotimes}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11192 provide for looping. Sometimes these are quicker to write than the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11193 equivalent @code{while} loop. Both are Lisp macros. (@xref{Macros, ,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11194 Macros, elisp, The GNU Emacs Lisp Reference Manual}. )
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11195
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11196 @code{dolist} works like a @code{while} loop that `@sc{cdr}s down a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11197 list': @code{dolist} automatically shortens the list each time it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11198 loops---takes the @sc{cdr} of the list---and binds the @sc{car} of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11199 each shorter version of the list to the first of its arguments.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11201 @code{dotimes} loops a specific number of times: you specify the number.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11202
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11203 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11204 * dolist::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11205 * dotimes::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11206 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11207
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11208 @node dolist, dotimes, dolist dotimes, dolist dotimes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11209 @unnumberedsubsubsec The @code{dolist} Macro
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11210 @findex dolist
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11211
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11212 Suppose, for example, you want to reverse a list, so that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11213 ``first'' ``second'' ``third'' becomes ``third'' ``second'' ``first''.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11214
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11215 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11216 In practice, you would use the @code{reverse} function, like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11217
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11218 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11219 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11220 (setq animals '(gazelle giraffe lion tiger))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11221
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11222 (reverse animals)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11223 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11224 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11225
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11226 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11227 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11228 Here is how you could reverse the list using a @code{while} loop:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11229
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11230 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11231 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11232 (setq animals '(gazelle giraffe lion tiger))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11233
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11234 (defun reverse-list-with-while (list)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11235 "Using while, reverse the order of LIST."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11236 (let (value) ; make sure list starts empty
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11237 (while list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11238 (setq value (cons (car list) value))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11239 (setq list (cdr list)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11240 value))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11241
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11242 (reverse-list-with-while animals)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11243 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11244 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11245
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11246 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11247 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11248 And here is how you could use the @code{dolist} macro:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11249
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11250 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11251 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11252 (setq animals '(gazelle giraffe lion tiger))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11253
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11254 (defun reverse-list-with-dolist (list)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11255 "Using dolist, reverse the order of LIST."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11256 (let (value) ; make sure list starts empty
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11257 (dolist (element list value)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11258 (setq value (cons element value)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11259
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11260 (reverse-list-with-dolist animals)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11261 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11262 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11263
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11264 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11265 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11266 In Info, you can place your cursor after the closing parenthesis of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11267 each expression and type @kbd{C-x C-e}; in each case, you should see
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11268
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11269 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11270 (tiger lion giraffe gazelle)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11271 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11272
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11273 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11274 in the echo area.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11275
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11276 For this example, the existing @code{reverse} function is obviously best.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11277 The @code{while} loop is just like our first example (@pxref{Loop
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11278 Example, , A @code{while} Loop and a List}). The @code{while} first
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11279 checks whether the list has elements; if so, it constructs a new list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11280 by adding the first element of the list to the existing list (which in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11281 the first iteration of the loop is @code{nil}). Since the second
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11282 element is prepended in front of the first element, and the third
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11283 element is prepended in front of the second element, the list is reversed.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11284
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11285 In the expression using a @code{while} loop,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11286 the @w{@code{(setq list (cdr list))}}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11287 expression shortens the list, so the @code{while} loop eventually
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11288 stops. In addition, it provides the @code{cons} expression with a new
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11289 first element by creating a new and shorter list at each repetition of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11290 the loop.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11291
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11292 The @code{dolist} expression does very much the same as the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11293 @code{while} expression, except that the @code{dolist} macro does some
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11294 of the work you have to do when writing a @code{while} expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11295
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11296 Like a @code{while} loop, a @code{dolist} loops. What is different is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11297 that it automatically shortens the list each time it loops --- it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11298 `@sc{cdr}s down the list' on its own --- and it automatically binds
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11299 the @sc{car} of each shorter version of the list to the first of its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11300 arguments.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11301
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11302 In the example, the @sc{car} of each shorter version of the list is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11303 referred to using the symbol @samp{element}, the list itself is called
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11304 @samp{list}, and the value returned is called @samp{value}. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11305 remainder of the @code{dolist} expression is the body.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11306
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11307 The @code{dolist} expression binds the @sc{car} of each shorter
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11308 version of the list to @code{element} and then evaluates the body of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11309 the expression; and repeats the loop. The result is returned in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11310 @code{value}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11311
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11312 @node dotimes, , dolist, dolist dotimes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11313 @unnumberedsubsubsec The @code{dotimes} Macro
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11314 @findex dotimes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11315
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11316 The @code{dotimes} macro is similar to @code{dolist}, except that it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11317 loops a specific number of times.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11318
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11319 The first argument to @code{dotimes} is assigned the numbers 0, 1, 2
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11320 and so forth each time around the loop, and the value of the third
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11321 argument is returned. You need to provide the value of the second
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11322 argument, which is how many times the macro loops.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11323
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11324 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11325 For example, the following binds the numbers from 0 up to, but not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11326 including, the number 3 to the first argument, @var{number}, and then
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11327 constructs a list of the three numbers. (The first number is 0, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11328 second number is 1, and the third number is 2; this makes a total of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11329 three numbers in all, starting with zero as the first number.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11330
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11331 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11332 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11333 (let (value) ; otherwise a value is a void variable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11334 (dotimes (number 3 value)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11335 (setq value (cons number value))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11336
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11337 @result{} (2 1 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11338 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11339 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11340
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11341 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11342 @code{dotimes} returns @code{value}, so the way to use
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11343 @code{dotimes} is to operate on some expression @var{number} number of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11344 times and then return the result, either as a list or an atom.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11345
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11346 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11347 Here is an example of a @code{defun} that uses @code{dotimes} to add
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11348 up the number of pebbles in a triangle.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11349
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11350 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11351 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11352 (defun triangle-using-dotimes (number-of-rows)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11353 "Using dotimes, add up the number of pebbles in a triangle."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11354 (let ((total 0)) ; otherwise a total is a void variable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11355 (dotimes (number number-of-rows total)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11356 (setq total (+ total (1+ number))))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11357
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11358 (triangle-using-dotimes 4)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11359 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11360 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11361
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11362 @node Recursion, Looping exercise, dolist dotimes, Loops & Recursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11363 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11364 @section Recursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11365 @cindex Recursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11366
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11367 A recursive function contains code that tells the Lisp interpreter to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11368 call a program that runs exactly like itself, but with slightly
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11369 different arguments. The code runs exactly the same because it has
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11370 the same name. However, even though the program has the same name, it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11371 is not the same entity. It is different. In the jargon, it is a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11372 different `instance'.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11373
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11374 Eventually, if the program is written correctly, the `slightly
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11375 different arguments' will become sufficiently different from the first
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11376 arguments that the final instance will stop.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11377
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11378 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11379 * Building Robots:: Same model, different serial number ...
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11380 * Recursive Definition Parts:: Walk until you stop ...
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11381 * Recursion with list:: Using a list as the test whether to recurse.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11382 * Recursive triangle function::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11383 * Recursion with cond::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11384 * Recursive Patterns:: Often used templates.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11385 * No Deferment:: Don't store up work ...
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11386 * No deferment solution::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11387 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11388
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11389 @node Building Robots, Recursive Definition Parts, Recursion, Recursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11390 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11391 @subsection Building Robots: Extending the Metaphor
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11392 @cindex Building robots
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11393 @cindex Robots, building
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11394
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11395 It is sometimes helpful to think of a running program as a robot that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11396 does a job. In doing its job, a recursive function calls on a second
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11397 robot to help it. The second robot is identical to the first in every
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11398 way, except that the second robot helps the first and has been
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11399 passed different arguments than the first.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11400
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11401 In a recursive function, the second robot may call a third; and the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11402 third may call a fourth, and so on. Each of these is a different
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11403 entity; but all are clones.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11404
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11405 Since each robot has slightly different instructions---the arguments
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11406 will differ from one robot to the next---the last robot should know
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11407 when to stop.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11408
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11409 Let's expand on the metaphor in which a computer program is a robot.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11410
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11411 A function definition provides the blueprints for a robot. When you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11412 install a function definition, that is, when you evaluate a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11413 @code{defun} special form, you install the necessary equipment to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11414 build robots. It is as if you were in a factory, setting up an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11415 assembly line. Robots with the same name are built according to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11416 same blueprints. So they have, as it were, the same `model number',
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11417 but a different `serial number'.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11418
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11419 We often say that a recursive function `calls itself'. What we mean
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11420 is that the instructions in a recursive function cause the Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11421 interpreter to run a different function that has the same name and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11422 does the same job as the first, but with different arguments.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11423
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11424 It is important that the arguments differ from one instance to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11425 next; otherwise, the process will never stop.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11426
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11427 @node Recursive Definition Parts, Recursion with list, Building Robots, Recursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11428 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11429 @subsection The Parts of a Recursive Definition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11430 @cindex Parts of a Recursive Definition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11431 @cindex Recursive Definition Parts
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11432
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11433 A recursive function typically contains a conditional expression which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11434 has three parts:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11435
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11436 @enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11437 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11438 A true-or-false-test that determines whether the function is called
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11439 again, here called the @dfn{do-again-test}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11440
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11441 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11442 The name of the function. When this name is called, a new instance of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11443 the function---a new robot, as it were---is created and told what to do.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11444
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11445 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11446 An expression that returns a different value each time the function is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11447 called, here called the @dfn{next-step-expression}. Consequently, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11448 argument (or arguments) passed to the new instance of the function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11449 will be different from that passed to the previous instance. This
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11450 causes the conditional expression, the @dfn{do-again-test}, to test
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11451 false after the correct number of repetitions.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11452 @end enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11453
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11454 Recursive functions can be much simpler than any other kind of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11455 function. Indeed, when people first start to use them, they often look
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11456 so mysteriously simple as to be incomprehensible. Like riding a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11457 bicycle, reading a recursive function definition takes a certain knack
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11458 which is hard at first but then seems simple.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11459
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11460 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11461 There are several different common recursive patterns. A very simple
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11462 pattern looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11463
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11464 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11465 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11466 (defun @var{name-of-recursive-function} (@var{argument-list})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11467 "@var{documentation}@dots{}"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11468 (if @var{do-again-test}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11469 @var{body}@dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11470 (@var{name-of-recursive-function}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11471 @var{next-step-expression})))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11472 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11473 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11474
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11475 Each time a recursive function is evaluated, a new instance of it is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11476 created and told what to do. The arguments tell the instance what to do.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11477
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11478 An argument is bound to the value of the next-step-expression. Each
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11479 instance runs with a different value of the next-step-expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11480
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11481 The value in the next-step-expression is used in the do-again-test.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11482
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11483 The value returned by the next-step-expression is passed to the new
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11484 instance of the function, which evaluates it (or some
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11485 transmogrification of it) to determine whether to continue or stop.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11486 The next-step-expression is designed so that the do-again-test returns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11487 false when the function should no longer be repeated.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11488
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11489 The do-again-test is sometimes called the @dfn{stop condition},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11490 since it stops the repetitions when it tests false.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11491
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11492 @node Recursion with list, Recursive triangle function, Recursive Definition Parts, Recursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11493 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11494 @subsection Recursion with a List
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11495
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11496 The example of a @code{while} loop that printed the elements of a list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11497 of numbers can be written recursively. Here is the code, including
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11498 an expression to set the value of the variable @code{animals} to a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11499
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11500 If you are using GNU Emacs 20 or before, this example must be copied
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11501 to the @file{*scratch*} buffer and each expression must be evaluated
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11502 there. Use @kbd{C-u C-x C-e} to evaluate the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11503 @code{(print-elements-recursively animals)} expression so that the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11504 results are printed in the buffer; otherwise the Lisp interpreter will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11505 try to squeeze the results into the one line of the echo area.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11506
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11507 Also, place your cursor immediately after the last closing parenthesis
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11508 of the @code{print-elements-recursively} function, before the comment.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11509 Otherwise, the Lisp interpreter will try to evaluate the comment.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11510
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11511 If you are using a more recent version of Emacs, you can evaluate this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11512 expression directly in Info.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11513
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11514 @findex print-elements-recursively
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11515 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11516 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11517 (setq animals '(gazelle giraffe lion tiger))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11518
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11519 (defun print-elements-recursively (list)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11520 "Print each element of LIST on a line of its own.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11521 Uses recursion."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11522 (when list ; @r{do-again-test}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11523 (print (car list)) ; @r{body}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11524 (print-elements-recursively ; @r{recursive call}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11525 (cdr list)))) ; @r{next-step-expression}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11526
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11527 (print-elements-recursively animals)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11528 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11529 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11530
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11531 The @code{print-elements-recursively} function first tests whether
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11532 there is any content in the list; if there is, the function prints the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11533 first element of the list, the @sc{car} of the list. Then the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11534 function `invokes itself', but gives itself as its argument, not the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11535 whole list, but the second and subsequent elements of the list, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11536 @sc{cdr} of the list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11537
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11538 Put another way, if the list is not empty, the function invokes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11539 another instance of code that is similar to the initial code, but is a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11540 different thread of execution, with different arguments than the first
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11541 instance.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11542
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11543 Put in yet another way, if the list is not empty, the first robot
98770
c9c8b8c7805c Sean Sieger <sean.sieger at gmail.com> (tiny change)
Glenn Morris <rgm@gnu.org>
parents: 98525
diff changeset
11544 assembles a second robot and tells it what to do; the second robot is
83955
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11545 a different individual from the first, but is the same model.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11546
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11547 When the second evaluation occurs, the @code{when} expression is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11548 evaluated and if true, prints the first element of the list it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11549 receives as its argument (which is the second element of the original
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11550 list). Then the function `calls itself' with the @sc{cdr} of the list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11551 it is invoked with, which (the second time around) is the @sc{cdr} of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11552 the @sc{cdr} of the original list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11553
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11554 Note that although we say that the function `calls itself', what we
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11555 mean is that the Lisp interpreter assembles and instructs a new
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11556 instance of the program. The new instance is a clone of the first,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11557 but is a separate individual.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11558
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11559 Each time the function `invokes itself', it invokes itself on a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11560 shorter version of the original list. It creates a new instance that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11561 works on a shorter list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11562
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11563 Eventually, the function invokes itself on an empty list. It creates
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11564 a new instance whose argument is @code{nil}. The conditional expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11565 tests the value of @code{list}. Since the value of @code{list} is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11566 @code{nil}, the @code{when} expression tests false so the then-part is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11567 not evaluated. The function as a whole then returns @code{nil}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11568
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11569 @need 1200
98525
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
11570 When you evaluate the expression @code{(print-elements-recursively
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
11571 animals)} in the @file{*scratch*} buffer, you see this result:
83955
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11572
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11573 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11574 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11575 gazelle
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11576
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11577 giraffe
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11578
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11579 lion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11580
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11581 tiger
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11582 nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11583 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11584 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11585
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11586 @need 2000
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11587 @node Recursive triangle function, Recursion with cond, Recursion with list, Recursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11588 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11589 @subsection Recursion in Place of a Counter
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11590 @findex triangle-recursively
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11591
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11592 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11593 The @code{triangle} function described in a previous section can also
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11594 be written recursively. It looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11595
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11596 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11597 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11598 (defun triangle-recursively (number)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11599 "Return the sum of the numbers 1 through NUMBER inclusive.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11600 Uses recursion."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11601 (if (= number 1) ; @r{do-again-test}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11602 1 ; @r{then-part}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11603 (+ number ; @r{else-part}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11604 (triangle-recursively ; @r{recursive call}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11605 (1- number))))) ; @r{next-step-expression}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11606
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11607 (triangle-recursively 7)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11608 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11609 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11610
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11611 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11612 You can install this function by evaluating it and then try it by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11613 evaluating @code{(triangle-recursively 7)}. (Remember to put your
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11614 cursor immediately after the last parenthesis of the function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11615 definition, before the comment.) The function evaluates to 28.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11616
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11617 To understand how this function works, let's consider what happens in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11618 various cases when the function is passed 1, 2, 3, or 4 as the value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11619 its argument.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11620
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11621 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11622 * Recursive Example arg of 1 or 2::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11623 * Recursive Example arg of 3 or 4::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11624 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11625
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11626 @node Recursive Example arg of 1 or 2, Recursive Example arg of 3 or 4, Recursive triangle function, Recursive triangle function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11627 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11628 @unnumberedsubsubsec An argument of 1 or 2
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11629 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11630
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11631 First, what happens if the value of the argument is 1?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11632
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11633 The function has an @code{if} expression after the documentation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11634 string. It tests whether the value of @code{number} is equal to 1; if
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11635 so, Emacs evaluates the then-part of the @code{if} expression, which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11636 returns the number 1 as the value of the function. (A triangle with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11637 one row has one pebble in it.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11638
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11639 Suppose, however, that the value of the argument is 2. In this case,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11640 Emacs evaluates the else-part of the @code{if} expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11641
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11642 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11643 The else-part consists of an addition, the recursive call to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11644 @code{triangle-recursively} and a decrementing action; and it looks like
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11645 this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11646
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11647 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11648 (+ number (triangle-recursively (1- number)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11649 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11650
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11651 When Emacs evaluates this expression, the innermost expression is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11652 evaluated first; then the other parts in sequence. Here are the steps
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11653 in detail:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11654
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11655 @table @i
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11656 @item Step 1 @w{ } Evaluate the innermost expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11657
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11658 The innermost expression is @code{(1- number)} so Emacs decrements the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11659 value of @code{number} from 2 to 1.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11660
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11661 @item Step 2 @w{ } Evaluate the @code{triangle-recursively} function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11662
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11663 The Lisp interpreter creates an individual instance of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11664 @code{triangle-recursively}. It does not matter that this function is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11665 contained within itself. Emacs passes the result Step 1 as the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11666 argument used by this instance of the @code{triangle-recursively}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11667 function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11668
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11669 In this case, Emacs evaluates @code{triangle-recursively} with an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11670 argument of 1. This means that this evaluation of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11671 @code{triangle-recursively} returns 1.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11672
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11673 @item Step 3 @w{ } Evaluate the value of @code{number}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11674
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11675 The variable @code{number} is the second element of the list that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11676 starts with @code{+}; its value is 2.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11677
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11678 @item Step 4 @w{ } Evaluate the @code{+} expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11679
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11680 The @code{+} expression receives two arguments, the first
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11681 from the evaluation of @code{number} (Step 3) and the second from the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11682 evaluation of @code{triangle-recursively} (Step 2).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11683
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11684 The result of the addition is the sum of 2 plus 1, and the number 3 is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11685 returned, which is correct. A triangle with two rows has three
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11686 pebbles in it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11687 @end table
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11688
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11689 @node Recursive Example arg of 3 or 4, , Recursive Example arg of 1 or 2, Recursive triangle function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11690 @unnumberedsubsubsec An argument of 3 or 4
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11691
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11692 Suppose that @code{triangle-recursively} is called with an argument of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11693 3.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11694
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11695 @table @i
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11696 @item Step 1 @w{ } Evaluate the do-again-test.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11697
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11698 The @code{if} expression is evaluated first. This is the do-again
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11699 test and returns false, so the else-part of the @code{if} expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11700 is evaluated. (Note that in this example, the do-again-test causes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11701 the function to call itself when it tests false, not when it tests
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11702 true.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11703
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11704 @item Step 2 @w{ } Evaluate the innermost expression of the else-part.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11705
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11706 The innermost expression of the else-part is evaluated, which decrements
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11707 3 to 2. This is the next-step-expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11708
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11709 @item Step 3 @w{ } Evaluate the @code{triangle-recursively} function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11710
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11711 The number 2 is passed to the @code{triangle-recursively} function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11712
98525
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
11713 We already know what happens when Emacs evaluates @code{triangle-recursively} with
83955
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11714 an argument of 2. After going through the sequence of actions described
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11715 earlier, it returns a value of 3. So that is what will happen here.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11716
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11717 @item Step 4 @w{ } Evaluate the addition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11718
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11719 3 will be passed as an argument to the addition and will be added to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11720 number with which the function was called, which is 3.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11721 @end table
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11722
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11723 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11724 The value returned by the function as a whole will be 6.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11725
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11726 Now that we know what will happen when @code{triangle-recursively} is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11727 called with an argument of 3, it is evident what will happen if it is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11728 called with an argument of 4:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11729
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11730 @quotation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11731 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11732 In the recursive call, the evaluation of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11733
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11734 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11735 (triangle-recursively (1- 4))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11736 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11737
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11738 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11739 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11740 will return the value of evaluating
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11741
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11742 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11743 (triangle-recursively 3)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11744 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11745
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11746 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11747 which is 6 and this value will be added to 4 by the addition in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11748 third line.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11749 @end quotation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11750
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11751 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11752 The value returned by the function as a whole will be 10.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11753
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11754 Each time @code{triangle-recursively} is evaluated, it evaluates a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11755 version of itself---a different instance of itself---with a smaller
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11756 argument, until the argument is small enough so that it does not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11757 evaluate itself.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11758
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11759 Note that this particular design for a recursive function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11760 requires that operations be deferred.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11761
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11762 Before @code{(triangle-recursively 7)} can calculate its answer, it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11763 must call @code{(triangle-recursively 6)}; and before
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11764 @code{(triangle-recursively 6)} can calculate its answer, it must call
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11765 @code{(triangle-recursively 5)}; and so on. That is to say, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11766 calculation that @code{(triangle-recursively 7)} makes must be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11767 deferred until @code{(triangle-recursively 6)} makes its calculation;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11768 and @code{(triangle-recursively 6)} must defer until
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11769 @code{(triangle-recursively 5)} completes; and so on.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11770
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11771 If each of these instances of @code{triangle-recursively} are thought
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11772 of as different robots, the first robot must wait for the second to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11773 complete its job, which must wait until the third completes, and so
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11774 on.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11775
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11776 There is a way around this kind of waiting, which we will discuss in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11777 @ref{No Deferment, , Recursion without Deferments}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11778
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11779 @node Recursion with cond, Recursive Patterns, Recursive triangle function, Recursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11780 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11781 @subsection Recursion Example Using @code{cond}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11782 @findex cond
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11783
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11784 The version of @code{triangle-recursively} described earlier is written
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11785 with the @code{if} special form. It can also be written using another
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11786 special form called @code{cond}. The name of the special form
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11787 @code{cond} is an abbreviation of the word @samp{conditional}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11788
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11789 Although the @code{cond} special form is not used as often in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11790 Emacs Lisp sources as @code{if}, it is used often enough to justify
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11791 explaining it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11792
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11793 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11794 The template for a @code{cond} expression looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11795
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11796 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11797 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11798 (cond
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11799 @var{body}@dots{})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11800 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11801 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11802
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11803 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11804 where the @var{body} is a series of lists.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11805
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11806 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11807 Written out more fully, the template looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11808
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11809 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11810 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11811 (cond
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11812 (@var{first-true-or-false-test} @var{first-consequent})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11813 (@var{second-true-or-false-test} @var{second-consequent})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11814 (@var{third-true-or-false-test} @var{third-consequent})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11815 @dots{})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11816 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11817 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11818
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11819 When the Lisp interpreter evaluates the @code{cond} expression, it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11820 evaluates the first element (the @sc{car} or true-or-false-test) of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11821 the first expression in a series of expressions within the body of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11822 @code{cond}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11823
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11824 If the true-or-false-test returns @code{nil} the rest of that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11825 expression, the consequent, is skipped and the true-or-false-test of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11826 next expression is evaluated. When an expression is found whose
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11827 true-or-false-test returns a value that is not @code{nil}, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11828 consequent of that expression is evaluated. The consequent can be one
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11829 or more expressions. If the consequent consists of more than one
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11830 expression, the expressions are evaluated in sequence and the value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11831 the last one is returned. If the expression does not have a consequent,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11832 the value of the true-or-false-test is returned.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11833
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11834 If none of the true-or-false-tests test true, the @code{cond} expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11835 returns @code{nil}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11836
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11837 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11838 Written using @code{cond}, the @code{triangle} function looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11839
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11840 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11841 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11842 (defun triangle-using-cond (number)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11843 (cond ((<= number 0) 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11844 ((= number 1) 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11845 ((> number 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11846 (+ number (triangle-using-cond (1- number))))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11847 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11848 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11849
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11850 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11851 In this example, the @code{cond} returns 0 if the number is less than or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11852 equal to 0, it returns 1 if the number is 1 and it evaluates @code{(+
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11853 number (triangle-using-cond (1- number)))} if the number is greater than
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11854 1.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11855
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11856 @node Recursive Patterns, No Deferment, Recursion with cond, Recursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11857 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11858 @subsection Recursive Patterns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11859 @cindex Recursive Patterns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11860
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11861 Here are three common recursive patterns. Each involves a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11862 Recursion does not need to involve lists, but Lisp is designed for lists
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11863 and this provides a sense of its primal capabilities.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11864
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11865 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11866 * Every::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11867 * Accumulate::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11868 * Keep::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11869 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11870
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11871 @node Every, Accumulate, Recursive Patterns, Recursive Patterns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11872 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11873 @unnumberedsubsubsec Recursive Pattern: @emph{every}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11874 @cindex Every, type of recursive pattern
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11875 @cindex Recursive pattern: every
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11876
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11877 In the @code{every} recursive pattern, an action is performed on every
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11878 element of a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11879
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11880 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11881 The basic pattern is:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11882
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11883 @itemize @bullet
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11884 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11885 If a list be empty, return @code{nil}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11886 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11887 Else, act on the beginning of the list (the @sc{car} of the list)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11888 @itemize @minus
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11889 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11890 through a recursive call by the function on the rest (the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11891 @sc{cdr}) of the list,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11892 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11893 and, optionally, combine the acted-on element, using @code{cons},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11894 with the results of acting on the rest.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11895 @end itemize
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11896 @end itemize
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11897
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11898 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11899 Here is example:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11900
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11901 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11902 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11903 (defun square-each (numbers-list)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11904 "Square each of a NUMBERS LIST, recursively."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11905 (if (not numbers-list) ; do-again-test
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11906 nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11907 (cons
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11908 (* (car numbers-list) (car numbers-list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11909 (square-each (cdr numbers-list))))) ; next-step-expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11910 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11911
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11912 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11913 (square-each '(1 2 3))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11914 @result{} (1 4 9)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11915 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11916 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11917
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11918 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11919 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11920 If @code{numbers-list} is empty, do nothing. But if it has content,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11921 construct a list combining the square of the first number in the list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11922 with the result of the recursive call.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11923
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11924 (The example follows the pattern exactly: @code{nil} is returned if
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11925 the numbers' list is empty. In practice, you would write the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11926 conditional so it carries out the action when the numbers' list is not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11927 empty.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11928
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11929 The @code{print-elements-recursively} function (@pxref{Recursion with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11930 list, , Recursion with a List}) is another example of an @code{every}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11931 pattern, except in this case, rather than bring the results together
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11932 using @code{cons}, we print each element of output.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11933
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11934 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11935 The @code{print-elements-recursively} function looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11936
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11937 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11938 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11939 (setq animals '(gazelle giraffe lion tiger))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11940 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11941
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11942 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11943 (defun print-elements-recursively (list)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11944 "Print each element of LIST on a line of its own.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11945 Uses recursion."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11946 (when list ; @r{do-again-test}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11947 (print (car list)) ; @r{body}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11948 (print-elements-recursively ; @r{recursive call}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11949 (cdr list)))) ; @r{next-step-expression}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11950
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11951 (print-elements-recursively animals)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11952 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11953 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11954
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11955 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11956 The pattern for @code{print-elements-recursively} is:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11957
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11958 @itemize @bullet
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11959 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11960 When the list is empty, do nothing.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11961 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11962 But when the list has at least one element,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11963 @itemize @minus
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11964 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11965 act on the beginning of the list (the @sc{car} of the list),
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11966 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11967 and make a recursive call on the rest (the @sc{cdr}) of the list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11968 @end itemize
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11969 @end itemize
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11970
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11971 @node Accumulate, Keep, Every, Recursive Patterns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11972 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11973 @unnumberedsubsubsec Recursive Pattern: @emph{accumulate}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11974 @cindex Accumulate, type of recursive pattern
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11975 @cindex Recursive pattern: accumulate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11976
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11977 Another recursive pattern is called the @code{accumulate} pattern. In
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11978 the @code{accumulate} recursive pattern, an action is performed on
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11979 every element of a list and the result of that action is accumulated
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11980 with the results of performing the action on the other elements.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11981
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11982 This is very like the `every' pattern using @code{cons}, except that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11983 @code{cons} is not used, but some other combiner.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11984
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11985 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11986 The pattern is:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11987
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11988 @itemize @bullet
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11989 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11990 If a list be empty, return zero or some other constant.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11991 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11992 Else, act on the beginning of the list (the @sc{car} of the list),
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11993 @itemize @minus
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11994 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11995 and combine that acted-on element, using @code{+} or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11996 some other combining function, with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11997 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11998 a recursive call by the function on the rest (the @sc{cdr}) of the list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11999 @end itemize
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12000 @end itemize
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12001
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12002 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12003 Here is an example:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12004
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12005 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12006 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12007 (defun add-elements (numbers-list)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12008 "Add the elements of NUMBERS-LIST together."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12009 (if (not numbers-list)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12010 0
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12011 (+ (car numbers-list) (add-elements (cdr numbers-list)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12012 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12013
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12014 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12015 (add-elements '(1 2 3 4))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12016 @result{} 10
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12017 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12018 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12019
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12020 @xref{Files List, , Making a List of Files}, for an example of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12021 accumulate pattern.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12022
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12023 @node Keep, , Accumulate, Recursive Patterns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12024 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12025 @unnumberedsubsubsec Recursive Pattern: @emph{keep}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12026 @cindex Keep, type of recursive pattern
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12027 @cindex Recursive pattern: keep
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12028
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12029 A third recursive pattern is called the @code{keep} pattern.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12030 In the @code{keep} recursive pattern, each element of a list is tested;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12031 the element is acted on and the results are kept only if the element
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12032 meets a criterion.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12033
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12034 Again, this is very like the `every' pattern, except the element is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12035 skipped unless it meets a criterion.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12036
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12037 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12038 The pattern has three parts:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12039
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12040 @itemize @bullet
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12041 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12042 If a list be empty, return @code{nil}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12043 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12044 Else, if the beginning of the list (the @sc{car} of the list) passes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12045 a test
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12046 @itemize @minus
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12047 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12048 act on that element and combine it, using @code{cons} with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12049 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12050 a recursive call by the function on the rest (the @sc{cdr}) of the list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12051 @end itemize
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12052 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12053 Otherwise, if the beginning of the list (the @sc{car} of the list) fails
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12054 the test
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12055 @itemize @minus
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12056 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12057 skip on that element,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12058 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12059 and, recursively call the function on the rest (the @sc{cdr}) of the list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12060 @end itemize
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12061 @end itemize
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12062
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12063 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12064 Here is an example that uses @code{cond}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12065
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12066 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12067 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12068 (defun keep-three-letter-words (word-list)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12069 "Keep three letter words in WORD-LIST."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12070 (cond
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12071 ;; First do-again-test: stop-condition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12072 ((not word-list) nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12073
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12074 ;; Second do-again-test: when to act
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12075 ((eq 3 (length (symbol-name (car word-list))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12076 ;; combine acted-on element with recursive call on shorter list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12077 (cons (car word-list) (keep-three-letter-words (cdr word-list))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12078
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12079 ;; Third do-again-test: when to skip element;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12080 ;; recursively call shorter list with next-step expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12081 (t (keep-three-letter-words (cdr word-list)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12082 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12083
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12084 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12085 (keep-three-letter-words '(one two three four five six))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12086 @result{} (one two six)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12087 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12088 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12089
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12090 It goes without saying that you need not use @code{nil} as the test for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12091 when to stop; and you can, of course, combine these patterns.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12092
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12093 @node No Deferment, No deferment solution, Recursive Patterns, Recursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12094 @subsection Recursion without Deferments
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12095 @cindex Deferment in recursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12096 @cindex Recursion without Deferments
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12097
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12098 Let's consider again what happens with the @code{triangle-recursively}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12099 function. We will find that the intermediate calculations are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12100 deferred until all can be done.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12101
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12102 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12103 Here is the function definition:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12104
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12105 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12106 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12107 (defun triangle-recursively (number)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12108 "Return the sum of the numbers 1 through NUMBER inclusive.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12109 Uses recursion."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12110 (if (= number 1) ; @r{do-again-test}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12111 1 ; @r{then-part}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12112 (+ number ; @r{else-part}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12113 (triangle-recursively ; @r{recursive call}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12114 (1- number))))) ; @r{next-step-expression}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12115 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12116 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12117
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12118 What happens when we call this function with a argument of 7?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12119
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12120 The first instance of the @code{triangle-recursively} function adds
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12121 the number 7 to the value returned by a second instance of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12122 @code{triangle-recursively}, an instance that has been passed an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12123 argument of 6. That is to say, the first calculation is:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12124
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12125 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12126 (+ 7 (triangle-recursively 6))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12127 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12128
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12129 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12130 The first instance of @code{triangle-recursively}---you may want to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12131 think of it as a little robot---cannot complete its job. It must hand
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12132 off the calculation for @code{(triangle-recursively 6)} to a second
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12133 instance of the program, to a second robot. This second individual is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12134 completely different from the first one; it is, in the jargon, a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12135 `different instantiation'. Or, put another way, it is a different
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12136 robot. It is the same model as the first; it calculates triangle
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12137 numbers recursively; but it has a different serial number.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12138
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12139 And what does @code{(triangle-recursively 6)} return? It returns the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12140 number 6 added to the value returned by evaluating
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12141 @code{triangle-recursively} with an argument of 5. Using the robot
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12142 metaphor, it asks yet another robot to help it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12143
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12144 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12145 Now the total is:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12146
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12147 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12148 (+ 7 6 (triangle-recursively 5))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12149 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12150
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12151 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12152 And what happens next?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12153
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12154 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12155 (+ 7 6 5 (triangle-recursively 4))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12156 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12157
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12158 Each time @code{triangle-recursively} is called, except for the last
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12159 time, it creates another instance of the program---another robot---and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12160 asks it to make a calculation.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12161
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12162 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12163 Eventually, the full addition is set up and performed:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12164
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12165 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12166 (+ 7 6 5 4 3 2 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12167 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12168
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12169 This design for the function defers the calculation of the first step
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12170 until the second can be done, and defers that until the third can be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12171 done, and so on. Each deferment means the computer must remember what
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12172 is being waited on. This is not a problem when there are only a few
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12173 steps, as in this example. But it can be a problem when there are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12174 more steps.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12175
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12176 @node No deferment solution, , No Deferment, Recursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12177 @subsection No Deferment Solution
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12178 @cindex No deferment solution
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12179 @cindex Defermentless solution
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12180 @cindex Solution without deferment
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12181
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12182 The solution to the problem of deferred operations is to write in a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12183 manner that does not defer operations@footnote{The phrase @dfn{tail
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12184 recursive} is used to describe such a process, one that uses
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12185 `constant space'.}. This requires
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12186 writing to a different pattern, often one that involves writing two
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12187 function definitions, an `initialization' function and a `helper'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12188 function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12189
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12190 The `initialization' function sets up the job; the `helper' function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12191 does the work.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12192
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12193 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12194 Here are the two function definitions for adding up numbers. They are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12195 so simple, I find them hard to understand.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12196
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12197 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12198 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12199 (defun triangle-initialization (number)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12200 "Return the sum of the numbers 1 through NUMBER inclusive.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12201 This is the `initialization' component of a two function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12202 duo that uses recursion."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12203 (triangle-recursive-helper 0 0 number))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12204 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12205 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12206
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12207 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12208 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12209 (defun triangle-recursive-helper (sum counter number)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12210 "Return SUM, using COUNTER, through NUMBER inclusive.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12211 This is the `helper' component of a two function duo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12212 that uses recursion."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12213 (if (> counter number)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12214 sum
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12215 (triangle-recursive-helper (+ sum counter) ; @r{sum}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12216 (1+ counter) ; @r{counter}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12217 number))) ; @r{number}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12218 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12219 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12220
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12221 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12222 Install both function definitions by evaluating them, then call
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12223 @code{triangle-initialization} with 2 rows:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12224
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12225 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12226 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12227 (triangle-initialization 2)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12228 @result{} 3
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12229 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12230 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12231
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12232 The `initialization' function calls the first instance of the `helper'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12233 function with three arguments: zero, zero, and a number which is the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12234 number of rows in the triangle.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12235
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12236 The first two arguments passed to the `helper' function are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12237 initialization values. These values are changed when
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12238 @code{triangle-recursive-helper} invokes new instances.@footnote{The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12239 jargon is mildly confusing: @code{triangle-recursive-helper} uses a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12240 process that is iterative in a procedure that is recursive. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12241 process is called iterative because the computer need only record the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12242 three values, @code{sum}, @code{counter}, and @code{number}; the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12243 procedure is recursive because the function `calls itself'. On the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12244 other hand, both the process and the procedure used by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12245 @code{triangle-recursively} are called recursive. The word
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12246 `recursive' has different meanings in the two contexts.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12247
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12248 Let's see what happens when we have a triangle that has one row. (This
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12249 triangle will have one pebble in it!)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12251 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12252 @code{triangle-initialization} will call its helper with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12253 the arguments @w{@code{0 0 1}}. That function will run the conditional
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12254 test whether @code{(> counter number)}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12255
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12256 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12257 (> 0 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12258 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12259
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12260 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12261 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12262 and find that the result is false, so it will invoke
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12263 the else-part of the @code{if} clause:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12264
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12265 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12266 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12267 (triangle-recursive-helper
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12268 (+ sum counter) ; @r{sum plus counter} @result{} @r{sum}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12269 (1+ counter) ; @r{increment counter} @result{} @r{counter}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12270 number) ; @r{number stays the same}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12271 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12272 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12273
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12274 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12275 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12276 which will first compute:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12277
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12278 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12279 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12280 (triangle-recursive-helper (+ 0 0) ; @r{sum}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12281 (1+ 0) ; @r{counter}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12282 1) ; @r{number}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12283 @exdent which is:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12284
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12285 (triangle-recursive-helper 0 1 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12286 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12287 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12288
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12289 Again, @code{(> counter number)} will be false, so again, the Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12290 interpreter will evaluate @code{triangle-recursive-helper}, creating a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12291 new instance with new arguments.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12292
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12293 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12294 This new instance will be;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12295
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12296 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12297 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12298 (triangle-recursive-helper
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12299 (+ sum counter) ; @r{sum plus counter} @result{} @r{sum}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12300 (1+ counter) ; @r{increment counter} @result{} @r{counter}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12301 number) ; @r{number stays the same}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12302
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12303 @exdent which is:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12304
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12305 (triangle-recursive-helper 1 2 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12306 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12307 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12308
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12309 In this case, the @code{(> counter number)} test will be true! So the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12310 instance will return the value of the sum, which will be 1, as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12311 expected.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12312
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12313 Now, let's pass @code{triangle-initialization} an argument
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12314 of 2, to find out how many pebbles there are in a triangle with two rows.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12315
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12316 That function calls @code{(triangle-recursive-helper 0 0 2)}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12317
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12318 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12319 In stages, the instances called will be:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12320
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12321 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12322 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12323 @r{sum counter number}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12324 (triangle-recursive-helper 0 1 2)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12325
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12326 (triangle-recursive-helper 1 2 2)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12327
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12328 (triangle-recursive-helper 3 3 2)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12329 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12330 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12331
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12332 When the last instance is called, the @code{(> counter number)} test
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12333 will be true, so the instance will return the value of @code{sum},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12334 which will be 3.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12335
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12336 This kind of pattern helps when you are writing functions that can use
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12337 many resources in a computer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12338
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12339 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12340 @node Looping exercise, , Recursion, Loops & Recursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12341 @section Looping Exercise
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12342
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12343 @itemize @bullet
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12344 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12345 Write a function similar to @code{triangle} in which each row has a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12346 value which is the square of the row number. Use a @code{while} loop.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12347
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12348 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12349 Write a function similar to @code{triangle} that multiplies instead of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12350 adds the values.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12351
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12352 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12353 Rewrite these two functions recursively. Rewrite these functions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12354 using @code{cond}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12355
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12356 @c comma in printed title causes problem in Info cross reference
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12357 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12358 Write a function for Texinfo mode that creates an index entry at the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12359 beginning of a paragraph for every @samp{@@dfn} within the paragraph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12360 (In a Texinfo file, @samp{@@dfn} marks a definition. This book is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12361 written in Texinfo.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12362
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12363 Many of the functions you will need are described in two of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12364 previous chapters, @ref{Cutting & Storing Text, , Cutting and Storing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12365 Text}, and @ref{Yanking, , Yanking Text Back}. If you use
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12366 @code{forward-paragraph} to put the index entry at the beginning of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12367 the paragraph, you will have to use @w{@kbd{C-h f}}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12368 (@code{describe-function}) to find out how to make the command go
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12369 backwards.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12370
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12371 For more information, see
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12372 @ifinfo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12373 @ref{Indicating, , Indicating Definitions, texinfo}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12374 @end ifinfo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12375 @ifhtml
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12376 @ref{Indicating, , Indicating, texinfo, Texinfo Manual}, which goes to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12377 a Texinfo manual in the current directory. Or, if you are on the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12378 Internet, see
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12379 @uref{http://www.gnu.org/software/texinfo/manual/texinfo/}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12380 @end ifhtml
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12381 @iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12382 ``Indicating Definitions, Commands, etc.'' in @cite{Texinfo, The GNU
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12383 Documentation Format}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12384 @end iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12385 @end itemize
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12386
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12387 @node Regexp Search, Counting Words, Loops & Recursion, Top
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12388 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12389 @chapter Regular Expression Searches
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12390 @cindex Searches, illustrating
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12391 @cindex Regular expression searches
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12392 @cindex Patterns, searching for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12393 @cindex Motion by sentence and paragraph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12394 @cindex Sentences, movement by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12395 @cindex Paragraphs, movement by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12396
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12397 Regular expression searches are used extensively in GNU Emacs. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12398 two functions, @code{forward-sentence} and @code{forward-paragraph},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12399 illustrate these searches well. They use regular expressions to find
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12400 where to move point. The phrase `regular expression' is often written
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12401 as `regexp'.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12402
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12403 Regular expression searches are described in @ref{Regexp Search, ,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12404 Regular Expression Search, emacs, The GNU Emacs Manual}, as well as in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12405 @ref{Regular Expressions, , , elisp, The GNU Emacs Lisp Reference
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12406 Manual}. In writing this chapter, I am presuming that you have at
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12407 least a mild acquaintance with them. The major point to remember is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12408 that regular expressions permit you to search for patterns as well as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12409 for literal strings of characters. For example, the code in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12410 @code{forward-sentence} searches for the pattern of possible
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12411 characters that could mark the end of a sentence, and moves point to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12412 that spot.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12413
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12414 Before looking at the code for the @code{forward-sentence} function, it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12415 is worth considering what the pattern that marks the end of a sentence
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12416 must be. The pattern is discussed in the next section; following that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12417 is a description of the regular expression search function,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12418 @code{re-search-forward}. The @code{forward-sentence} function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12419 is described in the section following. Finally, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12420 @code{forward-paragraph} function is described in the last section of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12421 this chapter. @code{forward-paragraph} is a complex function that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12422 introduces several new features.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12423
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12424 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12425 * sentence-end:: The regular expression for @code{sentence-end}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12426 * re-search-forward:: Very similar to @code{search-forward}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12427 * forward-sentence:: A straightforward example of regexp search.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12428 * forward-paragraph:: A somewhat complex example.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12429 * etags:: How to create your own @file{TAGS} table.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12430 * Regexp Review::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12431 * re-search Exercises::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12432 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12433
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12434 @node sentence-end, re-search-forward, Regexp Search, Regexp Search
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12435 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12436 @section The Regular Expression for @code{sentence-end}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12437 @findex sentence-end
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12438
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12439 The symbol @code{sentence-end} is bound to the pattern that marks the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12440 end of a sentence. What should this regular expression be?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12441
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12442 Clearly, a sentence may be ended by a period, a question mark, or an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12443 exclamation mark. Indeed, in English, only clauses that end with one
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12444 of those three characters should be considered the end of a sentence.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12445 This means that the pattern should include the character set:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12446
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12447 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12448 [.?!]
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12449 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12450
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12451 However, we do not want @code{forward-sentence} merely to jump to a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12452 period, a question mark, or an exclamation mark, because such a character
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12453 might be used in the middle of a sentence. A period, for example, is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12454 used after abbreviations. So other information is needed.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12455
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12456 According to convention, you type two spaces after every sentence, but
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12457 only one space after a period, a question mark, or an exclamation mark in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12458 the body of a sentence. So a period, a question mark, or an exclamation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12459 mark followed by two spaces is a good indicator of an end of sentence.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12460 However, in a file, the two spaces may instead be a tab or the end of a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12461 line. This means that the regular expression should include these three
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12462 items as alternatives.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12463
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12464 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12465 This group of alternatives will look like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12466
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12467 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12468 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12469 \\($\\| \\| \\)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12470 ^ ^^
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12471 TAB SPC
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12472 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12473 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12474
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12475 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12476 Here, @samp{$} indicates the end of the line, and I have pointed out
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12477 where the tab and two spaces are inserted in the expression. Both are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12478 inserted by putting the actual characters into the expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12479
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12480 Two backslashes, @samp{\\}, are required before the parentheses and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12481 vertical bars: the first backslash quotes the following backslash in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12482 Emacs; and the second indicates that the following character, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12483 parenthesis or the vertical bar, is special.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12484
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12485 @need 1000
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12486 Also, a sentence may be followed by one or more carriage returns, like
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12487 this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12488
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12489 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12490 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12491 [
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12492 ]*
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12493 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12494 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12495
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12496 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12497 Like tabs and spaces, a carriage return is inserted into a regular
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12498 expression by inserting it literally. The asterisk indicates that the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12499 @key{RET} is repeated zero or more times.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12501 But a sentence end does not consist only of a period, a question mark or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12502 an exclamation mark followed by appropriate space: a closing quotation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12503 mark or a closing brace of some kind may precede the space. Indeed more
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12504 than one such mark or brace may precede the space. These require a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12505 expression that looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12506
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12507 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12508 []\"')@}]*
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12509 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12510
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12511 In this expression, the first @samp{]} is the first character in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12512 expression; the second character is @samp{"}, which is preceded by a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12513 @samp{\} to tell Emacs the @samp{"} is @emph{not} special. The last
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12514 three characters are @samp{'}, @samp{)}, and @samp{@}}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12515
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12516 All this suggests what the regular expression pattern for matching the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12517 end of a sentence should be; and, indeed, if we evaluate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12518 @code{sentence-end} we find that it returns the following value:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12519
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12520 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12521 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12522 sentence-end
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12523 @result{} "[.?!][]\"')@}]*\\($\\| \\| \\)[
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12524 ]*"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12525 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12526 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12527
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12528 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12529 (Well, not in GNU Emacs 22; that is because of an effort to make the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12530 process simpler and to handle more glyphs and languages. When the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12531 value of @code{sentence-end} is @code{nil}, then use the value defined
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12532 by the function @code{sentence-end}. (Here is a use of the difference
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12533 between a value and a function in Emacs Lisp.) The function returns a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12534 value constructed from the variables @code{sentence-end-base},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12535 @code{sentence-end-double-space}, @code{sentence-end-without-period},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12536 and @code{sentence-end-without-space}. The critical variable is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12537 @code{sentence-end-base}; its global value is similar to the one
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12538 described above but it also contains two additional quotation marks.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12539 These have differing degrees of curliness. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12540 @code{sentence-end-without-period} variable, when true, tells Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12541 that a sentence may end without a period, such as text in Thai.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12542
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12543 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12544 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12545 (Note that here the @key{TAB}, two spaces, and @key{RET} are shown
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12546 literally in the pattern.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12547
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12548 This regular expression can be deciphered as follows:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12549
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12550 @table @code
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12551 @item [.?!]
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12552 The first part of the pattern is the three characters, a period, a question
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12553 mark and an exclamation mark, within square brackets. The pattern must
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12554 begin with one or other of these characters.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12555
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12556 @item []\"')@}]*
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12557 The second part of the pattern is the group of closing braces and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12558 quotation marks, which can appear zero or more times. These may follow
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12559 the period, question mark or exclamation mark. In a regular expression,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12560 the backslash, @samp{\}, followed by the double quotation mark,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12561 @samp{"}, indicates the class of string-quote characters. Usually, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12562 double quotation mark is the only character in this class. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12563 asterisk, @samp{*}, indicates that the items in the previous group (the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12564 group surrounded by square brackets, @samp{[]}) may be repeated zero or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12565 more times.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12566
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12567 @item \\($\\| \\| \\)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12568 The third part of the pattern is one or other of: either the end of a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12569 line, or two blank spaces, or a tab. The double back-slashes are used
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12570 to prevent Emacs from reading the parentheses and vertical bars as part
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12571 of the search pattern; the parentheses are used to mark the group and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12572 the vertical bars are used to indicated that the patterns to either side
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12573 of them are alternatives. The dollar sign is used to indicate the end
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12574 of a line and both the two spaces and the tab are each inserted as is to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12575 indicate what they are.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12576
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12577 @item [@key{RET}]*
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12578 Finally, the last part of the pattern indicates that the end of the line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12579 or the whitespace following the period, question mark or exclamation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12580 mark may, but need not, be followed by one or more carriage returns. In
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12581 the pattern, the carriage return is inserted as an actual carriage
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12582 return between square brackets but here it is shown as @key{RET}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12583 @end table
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12584 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12585
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12586 @node re-search-forward, forward-sentence, sentence-end, Regexp Search
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12587 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12588 @section The @code{re-search-forward} Function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12589 @findex re-search-forward
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12590
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12591 The @code{re-search-forward} function is very like the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12592 @code{search-forward} function. (@xref{search-forward, , The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12593 @code{search-forward} Function}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12594
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12595 @code{re-search-forward} searches for a regular expression. If the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12596 search is successful, it leaves point immediately after the last
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12597 character in the target. If the search is backwards, it leaves point
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12598 just before the first character in the target. You may tell
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12599 @code{re-search-forward} to return @code{t} for true. (Moving point
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12600 is therefore a `side effect'.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12601
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12602 Like @code{search-forward}, the @code{re-search-forward} function takes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12603 four arguments:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12604
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12605 @enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12606 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12607 The first argument is the regular expression that the function searches
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12608 for. The regular expression will be a string between quotations marks.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12609
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12610 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12611 The optional second argument limits how far the function will search; it is a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12612 bound, which is specified as a position in the buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12613
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12614 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12615 The optional third argument specifies how the function responds to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12616 failure: @code{nil} as the third argument causes the function to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12617 signal an error (and print a message) when the search fails; any other
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12618 value causes it to return @code{nil} if the search fails and @code{t}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12619 if the search succeeds.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12620
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12621 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12622 The optional fourth argument is the repeat count. A negative repeat
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12623 count causes @code{re-search-forward} to search backwards.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12624 @end enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12625
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12626 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12627 The template for @code{re-search-forward} looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12628
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12629 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12630 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12631 (re-search-forward "@var{regular-expression}"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12632 @var{limit-of-search}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12633 @var{what-to-do-if-search-fails}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12634 @var{repeat-count})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12635 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12636 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12637
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12638 The second, third, and fourth arguments are optional. However, if you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12639 want to pass a value to either or both of the last two arguments, you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12640 must also pass a value to all the preceding arguments. Otherwise, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12641 Lisp interpreter will mistake which argument you are passing the value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12642 to.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12643
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12644 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12645 In the @code{forward-sentence} function, the regular expression will be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12646 the value of the variable @code{sentence-end}. In simple form, that is:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12647
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12648 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12649 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12650 "[.?!][]\"')@}]*\\($\\| \\| \\)[
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12651 ]*"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12652 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12653 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12654
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12655 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12656 The limit of the search will be the end of the paragraph (since a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12657 sentence cannot go beyond a paragraph). If the search fails, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12658 function will return @code{nil}; and the repeat count will be provided
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12659 by the argument to the @code{forward-sentence} function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12660
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12661 @node forward-sentence, forward-paragraph, re-search-forward, Regexp Search
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12662 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12663 @section @code{forward-sentence}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12664 @findex forward-sentence
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12665
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12666 The command to move the cursor forward a sentence is a straightforward
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12667 illustration of how to use regular expression searches in Emacs Lisp.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12668 Indeed, the function looks longer and more complicated than it is; this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12669 is because the function is designed to go backwards as well as forwards;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12670 and, optionally, over more than one sentence. The function is usually
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12671 bound to the key command @kbd{M-e}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12672
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12673 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12674 * Complete forward-sentence::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12675 * fwd-sentence while loops:: Two @code{while} loops.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12676 * fwd-sentence re-search:: A regular expression search.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12677 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12678
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12679 @node Complete forward-sentence, fwd-sentence while loops, forward-sentence, forward-sentence
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12680 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12681 @unnumberedsubsec Complete @code{forward-sentence} function definition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12682 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12683
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12684 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12685 Here is the code for @code{forward-sentence}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12686
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12687 @c in GNU Emacs 22
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12688 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12689 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12690 (defun forward-sentence (&optional arg)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12691 "Move forward to next `sentence-end'. With argument, repeat.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12692 With negative argument, move backward repeatedly to `sentence-beginning'.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12693
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12694 The variable `sentence-end' is a regular expression that matches ends of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12695 sentences. Also, every paragraph boundary terminates sentences as well."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12696 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12697 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12698 (interactive "p")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12699 (or arg (setq arg 1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12700 (let ((opoint (point))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12701 (sentence-end (sentence-end)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12702 (while (< arg 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12703 (let ((pos (point))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12704 (par-beg (save-excursion (start-of-paragraph-text) (point))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12705 (if (and (re-search-backward sentence-end par-beg t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12706 (or (< (match-end 0) pos)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12707 (re-search-backward sentence-end par-beg t)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12708 (goto-char (match-end 0))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12709 (goto-char par-beg)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12710 (setq arg (1+ arg)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12711 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12712 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12713 (while (> arg 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12714 (let ((par-end (save-excursion (end-of-paragraph-text) (point))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12715 (if (re-search-forward sentence-end par-end t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12716 (skip-chars-backward " \t\n")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12717 (goto-char par-end)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12718 (setq arg (1- arg)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12719 (constrain-to-field nil opoint t)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12720 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12721 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12722
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12723 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12724 GNU Emacs 21
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12725 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12726 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12727 (defun forward-sentence (&optional arg)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12728 "Move forward to next sentence-end. With argument, repeat.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12729 With negative argument, move backward repeatedly to sentence-beginning.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12730 Sentence ends are identified by the value of sentence-end
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12731 treated as a regular expression. Also, every paragraph boundary
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12732 terminates sentences as well."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12733 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12734 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12735 (interactive "p")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12736 (or arg (setq arg 1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12737 (while (< arg 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12738 (let ((par-beg
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12739 (save-excursion (start-of-paragraph-text) (point))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12740 (if (re-search-backward
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12741 (concat sentence-end "[^ \t\n]") par-beg t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12742 (goto-char (1- (match-end 0)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12743 (goto-char par-beg)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12744 (setq arg (1+ arg)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12745 (while (> arg 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12746 (let ((par-end
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12747 (save-excursion (end-of-paragraph-text) (point))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12748 (if (re-search-forward sentence-end par-end t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12749 (skip-chars-backward " \t\n")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12750 (goto-char par-end)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12751 (setq arg (1- arg))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12752 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12753 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12754 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12755
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12756 The function looks long at first sight and it is best to look at its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12757 skeleton first, and then its muscle. The way to see the skeleton is to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12758 look at the expressions that start in the left-most columns:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12759
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12760 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12761 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12762 (defun forward-sentence (&optional arg)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12763 "@var{documentation}@dots{}"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12764 (interactive "p")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12765 (or arg (setq arg 1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12766 (let ((opoint (point)) (sentence-end (sentence-end)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12767 (while (< arg 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12768 (let ((pos (point))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12769 (par-beg (save-excursion (start-of-paragraph-text) (point))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12770 @var{rest-of-body-of-while-loop-when-going-backwards}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12771 (while (> arg 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12772 (let ((par-end (save-excursion (end-of-paragraph-text) (point))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12773 @var{rest-of-body-of-while-loop-when-going-forwards}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12774 @var{handle-forms-and-equivalent}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12775 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12776 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12777
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12778 This looks much simpler! The function definition consists of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12779 documentation, an @code{interactive} expression, an @code{or}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12780 expression, a @code{let} expression, and @code{while} loops.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12781
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12782 Let's look at each of these parts in turn.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12783
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12784 We note that the documentation is thorough and understandable.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12785
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12786 The function has an @code{interactive "p"} declaration. This means
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12787 that the processed prefix argument, if any, is passed to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12788 function as its argument. (This will be a number.) If the function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12789 is not passed an argument (it is optional) then the argument
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12790 @code{arg} will be bound to 1.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12791
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12792 When @code{forward-sentence} is called non-interactively without an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12793 argument, @code{arg} is bound to @code{nil}. The @code{or} expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12794 handles this. What it does is either leave the value of @code{arg} as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12795 it is, but only if @code{arg} is bound to a value; or it sets the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12796 value of @code{arg} to 1, in the case when @code{arg} is bound to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12797 @code{nil}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12798
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12799 Next is a @code{let}. That specifies the values of two local
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12800 variables, @code{point} and @code{sentence-end}. The local value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12801 point, from before the search, is used in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12802 @code{constrain-to-field} function which handles forms and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12803 equivalents. The @code{sentence-end} variable is set by the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12804 @code{sentence-end} function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12805
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12806 @node fwd-sentence while loops, fwd-sentence re-search, Complete forward-sentence, forward-sentence
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12807 @unnumberedsubsec The @code{while} loops
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12808
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12809 Two @code{while} loops follow. The first @code{while} has a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12810 true-or-false-test that tests true if the prefix argument for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12811 @code{forward-sentence} is a negative number. This is for going
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12812 backwards. The body of this loop is similar to the body of the second
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12813 @code{while} clause, but it is not exactly the same. We will skip
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12814 this @code{while} loop and concentrate on the second @code{while}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12815 loop.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12816
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12817 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12818 The second @code{while} loop is for moving point forward. Its skeleton
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12819 looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12820
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12821 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12822 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12823 (while (> arg 0) ; @r{true-or-false-test}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12824 (let @var{varlist}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12825 (if (@var{true-or-false-test})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12826 @var{then-part}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12827 @var{else-part}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12828 (setq arg (1- arg)))) ; @code{while} @r{loop decrementer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12829 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12830 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12831
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12832 The @code{while} loop is of the decrementing kind.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12833 (@xref{Decrementing Loop, , A Loop with a Decrementing Counter}.) It
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12834 has a true-or-false-test that tests true so long as the counter (in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12835 this case, the variable @code{arg}) is greater than zero; and it has a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12836 decrementer that subtracts 1 from the value of the counter every time
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12837 the loop repeats.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12838
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12839 If no prefix argument is given to @code{forward-sentence}, which is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12840 the most common way the command is used, this @code{while} loop will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12841 run once, since the value of @code{arg} will be 1.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12842
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12843 The body of the @code{while} loop consists of a @code{let} expression,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12844 which creates and binds a local variable, and has, as its body, an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12845 @code{if} expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12846
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12847 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12848 The body of the @code{while} loop looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12849
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12850 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12851 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12852 (let ((par-end
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12853 (save-excursion (end-of-paragraph-text) (point))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12854 (if (re-search-forward sentence-end par-end t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12855 (skip-chars-backward " \t\n")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12856 (goto-char par-end)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12857 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12858 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12859
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12860 The @code{let} expression creates and binds the local variable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12861 @code{par-end}. As we shall see, this local variable is designed to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12862 provide a bound or limit to the regular expression search. If the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12863 search fails to find a proper sentence ending in the paragraph, it will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12864 stop on reaching the end of the paragraph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12865
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12866 But first, let us examine how @code{par-end} is bound to the value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12867 the end of the paragraph. What happens is that the @code{let} sets the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12868 value of @code{par-end} to the value returned when the Lisp interpreter
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12869 evaluates the expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12870
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12871 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12872 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12873 (save-excursion (end-of-paragraph-text) (point))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12874 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12875 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12876
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12877 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12878 In this expression, @code{(end-of-paragraph-text)} moves point to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12879 end of the paragraph, @code{(point)} returns the value of point, and then
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12880 @code{save-excursion} restores point to its original position. Thus,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12881 the @code{let} binds @code{par-end} to the value returned by the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12882 @code{save-excursion} expression, which is the position of the end of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12883 the paragraph. (The @code{end-of-paragraph-text} function uses
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12884 @code{forward-paragraph}, which we will discuss shortly.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12885
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12886 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12887 Emacs next evaluates the body of the @code{let}, which is an @code{if}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12888 expression that looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12889
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12890 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12891 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12892 (if (re-search-forward sentence-end par-end t) ; @r{if-part}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12893 (skip-chars-backward " \t\n") ; @r{then-part}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12894 (goto-char par-end))) ; @r{else-part}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12895 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12896 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12897
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12898 The @code{if} tests whether its first argument is true and if so,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12899 evaluates its then-part; otherwise, the Emacs Lisp interpreter
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12900 evaluates the else-part. The true-or-false-test of the @code{if}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12901 expression is the regular expression search.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12902
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12903 It may seem odd to have what looks like the `real work' of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12904 the @code{forward-sentence} function buried here, but this is a common
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12905 way this kind of operation is carried out in Lisp.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12906
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12907 @node fwd-sentence re-search, , fwd-sentence while loops, forward-sentence
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12908 @unnumberedsubsec The regular expression search
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12909
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12910 The @code{re-search-forward} function searches for the end of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12911 sentence, that is, for the pattern defined by the @code{sentence-end}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12912 regular expression. If the pattern is found---if the end of the sentence is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12913 found---then the @code{re-search-forward} function does two things:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12914
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12915 @enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12916 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12917 The @code{re-search-forward} function carries out a side effect, which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12918 is to move point to the end of the occurrence found.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12919
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12920 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12921 The @code{re-search-forward} function returns a value of true. This is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12922 the value received by the @code{if}, and means that the search was
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12923 successful.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12924 @end enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12925
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12926 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12927 The side effect, the movement of point, is completed before the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12928 @code{if} function is handed the value returned by the successful
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12929 conclusion of the search.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12930
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12931 When the @code{if} function receives the value of true from a successful
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12932 call to @code{re-search-forward}, the @code{if} evaluates the then-part,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12933 which is the expression @code{(skip-chars-backward " \t\n")}. This
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12934 expression moves backwards over any blank spaces, tabs or carriage
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12935 returns until a printed character is found and then leaves point after
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12936 the character. Since point has already been moved to the end of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12937 pattern that marks the end of the sentence, this action leaves point
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12938 right after the closing printed character of the sentence, which is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12939 usually a period.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12940
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12941 On the other hand, if the @code{re-search-forward} function fails to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12942 find a pattern marking the end of the sentence, the function returns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12943 false. The false then causes the @code{if} to evaluate its third
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12944 argument, which is @code{(goto-char par-end)}: it moves point to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12945 end of the paragraph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12946
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12947 (And if the text is in a form or equivalent, and point may not move
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12948 fully, then the @code{constrain-to-field} function comes into play.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12949
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12950 Regular expression searches are exceptionally useful and the pattern
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12951 illustrated by @code{re-search-forward}, in which the search is the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12952 test of an @code{if} expression, is handy. You will see or write code
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12953 incorporating this pattern often.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12954
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12955 @node forward-paragraph, etags, forward-sentence, Regexp Search
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12956 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12957 @section @code{forward-paragraph}: a Goldmine of Functions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12958 @findex forward-paragraph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12959
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12960 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12961 @c in GNU Emacs 22
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12962 (defun forward-paragraph (&optional arg)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12963 "Move forward to end of paragraph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12964 With argument ARG, do it ARG times;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12965 a negative argument ARG = -N means move backward N paragraphs.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12966
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12967 A line which `paragraph-start' matches either separates paragraphs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12968 \(if `paragraph-separate' matches it also) or is the first line of a paragraph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12969 A paragraph end is the beginning of a line which is not part of the paragraph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12970 to which the end of the previous line belongs, or the end of the buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12971 Returns the count of paragraphs left to move."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12972 (interactive "p")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12973 (or arg (setq arg 1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12974 (let* ((opoint (point))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12975 (fill-prefix-regexp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12976 (and fill-prefix (not (equal fill-prefix ""))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12977 (not paragraph-ignore-fill-prefix)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12978 (regexp-quote fill-prefix)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12979 ;; Remove ^ from paragraph-start and paragraph-sep if they are there.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12980 ;; These regexps shouldn't be anchored, because we look for them
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12981 ;; starting at the left-margin. This allows paragraph commands to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12982 ;; work normally with indented text.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12983 ;; This hack will not find problem cases like "whatever\\|^something".
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12984 (parstart (if (and (not (equal "" paragraph-start))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12985 (equal ?^ (aref paragraph-start 0)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12986 (substring paragraph-start 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12987 paragraph-start))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12988 (parsep (if (and (not (equal "" paragraph-separate))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12989 (equal ?^ (aref paragraph-separate 0)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12990 (substring paragraph-separate 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12991 paragraph-separate))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12992 (parsep
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12993 (if fill-prefix-regexp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12994 (concat parsep "\\|"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12995 fill-prefix-regexp "[ \t]*$")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12996 parsep))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12997 ;; This is used for searching.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12998 (sp-parstart (concat "^[ \t]*\\(?:" parstart "\\|" parsep "\\)"))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12999 start found-start)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13000 (while (and (< arg 0) (not (bobp)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13001 (if (and (not (looking-at parsep))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13002 (re-search-backward "^\n" (max (1- (point)) (point-min)) t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13003 (looking-at parsep))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13004 (setq arg (1+ arg))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13005 (setq start (point))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13006 ;; Move back over paragraph-separating lines.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13007 (forward-char -1) (beginning-of-line)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13008 (while (and (not (bobp))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13009 (progn (move-to-left-margin)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13010 (looking-at parsep)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13011 (forward-line -1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13012 (if (bobp)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13013 nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13014 (setq arg (1+ arg))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13015 ;; Go to end of the previous (non-separating) line.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13016 (end-of-line)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13017 ;; Search back for line that starts or separates paragraphs.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13018 (if (if fill-prefix-regexp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13019 ;; There is a fill prefix; it overrides parstart.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13020 (let (multiple-lines)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13021 (while (and (progn (beginning-of-line) (not (bobp)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13022 (progn (move-to-left-margin)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13023 (not (looking-at parsep)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13024 (looking-at fill-prefix-regexp))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13025 (unless (= (point) start)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13026 (setq multiple-lines t))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13027 (forward-line -1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13028 (move-to-left-margin)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13029 ;; This deleted code caused a long hanging-indent line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13030 ;; not to be filled together with the following lines.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13031 ;; ;; Don't move back over a line before the paragraph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13032 ;; ;; which doesn't start with fill-prefix
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13033 ;; ;; unless that is the only line we've moved over.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13034 ;; (and (not (looking-at fill-prefix-regexp))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13035 ;; multiple-lines
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13036 ;; (forward-line 1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13037 (not (bobp)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13038 (while (and (re-search-backward sp-parstart nil 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13039 (setq found-start t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13040 ;; Found a candidate, but need to check if it is a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13041 ;; REAL parstart.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13042 (progn (setq start (point))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13043 (move-to-left-margin)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13044 (not (looking-at parsep)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13045 (not (and (looking-at parstart)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13046 (or (not use-hard-newlines)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13047 (bobp)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13048 (get-text-property
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13049 (1- start) 'hard)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13050 (setq found-start nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13051 (goto-char start))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13052 found-start)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13053 ;; Found one.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13054 (progn
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13055 ;; Move forward over paragraph separators.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13056 ;; We know this cannot reach the place we started
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13057 ;; because we know we moved back over a non-separator.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13058 (while (and (not (eobp))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13059 (progn (move-to-left-margin)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13060 (looking-at parsep)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13061 (forward-line 1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13062 ;; If line before paragraph is just margin, back up to there.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13063 (end-of-line 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13064 (if (> (current-column) (current-left-margin))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13065 (forward-char 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13066 (skip-chars-backward " \t")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13067 (if (not (bolp))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13068 (forward-line 1))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13069 ;; No starter or separator line => use buffer beg.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13070 (goto-char (point-min))))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13071
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13072 (while (and (> arg 0) (not (eobp)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13073 ;; Move forward over separator lines...
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13074 (while (and (not (eobp))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13075 (progn (move-to-left-margin) (not (eobp)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13076 (looking-at parsep))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13077 (forward-line 1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13078 (unless (eobp) (setq arg (1- arg)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13079 ;; ... and one more line.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13080 (forward-line 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13081 (if fill-prefix-regexp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13082 ;; There is a fill prefix; it overrides parstart.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13083 (while (and (not (eobp))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13084 (progn (move-to-left-margin) (not (eobp)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13085 (not (looking-at parsep))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13086 (looking-at fill-prefix-regexp))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13087 (forward-line 1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13088 (while (and (re-search-forward sp-parstart nil 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13089 (progn (setq start (match-beginning 0))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13090 (goto-char start)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13091 (not (eobp)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13092 (progn (move-to-left-margin)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13093 (not (looking-at parsep)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13094 (or (not (looking-at parstart))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13095 (and use-hard-newlines
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13096 (not (get-text-property (1- start) 'hard)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13097 (forward-char 1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13098 (if (< (point) (point-max))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13099 (goto-char start))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13100 (constrain-to-field nil opoint t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13101 ;; Return the number of steps that could not be done.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13102 arg))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13103 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13104
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13105 The @code{forward-paragraph} function moves point forward to the end
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13106 of the paragraph. It is usually bound to @kbd{M-@}} and makes use of a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13107 number of functions that are important in themselves, including
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13108 @code{let*}, @code{match-beginning}, and @code{looking-at}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13109
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13110 The function definition for @code{forward-paragraph} is considerably
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13111 longer than the function definition for @code{forward-sentence}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13112 because it works with a paragraph, each line of which may begin with a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13113 fill prefix.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13114
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13115 A fill prefix consists of a string of characters that are repeated at
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13116 the beginning of each line. For example, in Lisp code, it is a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13117 convention to start each line of a paragraph-long comment with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13118 @samp{;;; }. In Text mode, four blank spaces make up another common
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13119 fill prefix, creating an indented paragraph. (@xref{Fill Prefix, , ,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13120 emacs, The GNU Emacs Manual}, for more information about fill
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13121 prefixes.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13122
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13123 The existence of a fill prefix means that in addition to being able to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13124 find the end of a paragraph whose lines begin on the left-most
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13125 column, the @code{forward-paragraph} function must be able to find the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13126 end of a paragraph when all or many of the lines in the buffer begin
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13127 with the fill prefix.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13128
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13129 Moreover, it is sometimes practical to ignore a fill prefix that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13130 exists, especially when blank lines separate paragraphs.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13131 This is an added complication.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13132
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13133 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13134 * forward-paragraph in brief:: Key parts of the function definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13135 * fwd-para let:: The @code{let*} expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13136 * fwd-para while:: The forward motion @code{while} loop.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13137 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13138
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13139 @node forward-paragraph in brief, fwd-para let, forward-paragraph, forward-paragraph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13140 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13141 @unnumberedsubsec Shortened @code{forward-paragraph} function definition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13142 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13143
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13144 Rather than print all of the @code{forward-paragraph} function, we
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13145 will only print parts of it. Read without preparation, the function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13146 can be daunting!
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13147
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13148 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13149 In outline, the function looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13150
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13151 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13152 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13153 (defun forward-paragraph (&optional arg)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13154 "@var{documentation}@dots{}"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13155 (interactive "p")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13156 (or arg (setq arg 1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13157 (let*
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13158 @var{varlist}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13159 (while (and (< arg 0) (not (bobp))) ; @r{backward-moving-code}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13160 @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13161 (while (and (> arg 0) (not (eobp))) ; @r{forward-moving-code}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13162 @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13163 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13164 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13165
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13166 The first parts of the function are routine: the function's argument
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13167 list consists of one optional argument. Documentation follows.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13168
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13169 The lower case @samp{p} in the @code{interactive} declaration means
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13170 that the processed prefix argument, if any, is passed to the function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13171 This will be a number, and is the repeat count of how many paragraphs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13172 point will move. The @code{or} expression in the next line handles
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13173 the common case when no argument is passed to the function, which occurs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13174 if the function is called from other code rather than interactively.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13175 This case was described earlier. (@xref{forward-sentence, The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13176 @code{forward-sentence} function}.) Now we reach the end of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13177 familiar part of this function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13178
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13179 @node fwd-para let, fwd-para while, forward-paragraph in brief, forward-paragraph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13180 @unnumberedsubsec The @code{let*} expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13181
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13182 The next line of the @code{forward-paragraph} function begins a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13183 @code{let*} expression. This is a different than @code{let}. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13184 symbol is @code{let*} not @code{let}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13185
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13186 The @code{let*} special form is like @code{let} except that Emacs sets
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13187 each variable in sequence, one after another, and variables in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13188 latter part of the varlist can make use of the values to which Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13189 set variables in the earlier part of the varlist.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13190
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13191 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13192 ( refappend save-excursion, , code save-excursion in code append-to-buffer .)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13193 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13194
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13195 (@ref{append save-excursion, , @code{save-excursion} in @code{append-to-buffer}}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13196
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13197 In the @code{let*} expression in this function, Emacs binds a total of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13198 seven variables: @code{opoint}, @code{fill-prefix-regexp},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13199 @code{parstart}, @code{parsep}, @code{sp-parstart}, @code{start}, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13200 @code{found-start}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13201
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13202 The variable @code{parsep} appears twice, first, to remove instances
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13203 of @samp{^}, and second, to handle fill prefixes.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13204
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13205 The variable @code{opoint} is just the value of @code{point}. As you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13206 can guess, it is used in a @code{constrain-to-field} expression, just
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13207 as in @code{forward-sentence}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13208
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13209 The variable @code{fill-prefix-regexp} is set to the value returned by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13210 evaluating the following list:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13211
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13212 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13213 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13214 (and fill-prefix
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13215 (not (equal fill-prefix ""))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13216 (not paragraph-ignore-fill-prefix)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13217 (regexp-quote fill-prefix))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13218 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13219 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13220
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13221 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13222 This is an expression whose first element is the @code{and} special form.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13223
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13224 As we learned earlier (@pxref{kill-new function, , The @code{kill-new}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13225 function}), the @code{and} special form evaluates each of its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13226 arguments until one of the arguments returns a value of @code{nil}, in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13227 which case the @code{and} expression returns @code{nil}; however, if
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13228 none of the arguments returns a value of @code{nil}, the value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13229 resulting from evaluating the last argument is returned. (Since such
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13230 a value is not @code{nil}, it is considered true in Lisp.) In other
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13231 words, an @code{and} expression returns a true value only if all its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13232 arguments are true.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13233 @findex and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13234
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13235 In this case, the variable @code{fill-prefix-regexp} is bound to a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13236 non-@code{nil} value only if the following four expressions produce a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13237 true (i.e., a non-@code{nil}) value when they are evaluated; otherwise,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13238 @code{fill-prefix-regexp} is bound to @code{nil}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13239
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13240 @table @code
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13241 @item fill-prefix
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13242 When this variable is evaluated, the value of the fill prefix, if any,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13243 is returned. If there is no fill prefix, this variable returns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13244 @code{nil}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13245
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13246 @item (not (equal fill-prefix "")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13247 This expression checks whether an existing fill prefix is an empty
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13248 string, that is, a string with no characters in it. An empty string is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13249 not a useful fill prefix.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13251 @item (not paragraph-ignore-fill-prefix)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13252 This expression returns @code{nil} if the variable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13253 @code{paragraph-ignore-fill-prefix} has been turned on by being set to a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13254 true value such as @code{t}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13255
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13256 @item (regexp-quote fill-prefix)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13257 This is the last argument to the @code{and} special form. If all the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13258 arguments to the @code{and} are true, the value resulting from
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13259 evaluating this expression will be returned by the @code{and} expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13260 and bound to the variable @code{fill-prefix-regexp},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13261 @end table
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13262
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13263 @findex regexp-quote
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13264 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13265 The result of evaluating this @code{and} expression successfully is that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13266 @code{fill-prefix-regexp} will be bound to the value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13267 @code{fill-prefix} as modified by the @code{regexp-quote} function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13268 What @code{regexp-quote} does is read a string and return a regular
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13269 expression that will exactly match the string and match nothing else.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13270 This means that @code{fill-prefix-regexp} will be set to a value that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13271 will exactly match the fill prefix if the fill prefix exists.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13272 Otherwise, the variable will be set to @code{nil}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13273
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13274 The next two local variables in the @code{let*} expression are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13275 designed to remove instances of @samp{^} from @code{parstart} and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13276 @code{parsep}, the local variables which indicate the paragraph start
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13277 and the paragraph separator. The next expression sets @code{parsep}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13278 again. That is to handle fill prefixes.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13279
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13280 This is the setting that requires the definition call @code{let*}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13281 rather than @code{let}. The true-or-false-test for the @code{if}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13282 depends on whether the variable @code{fill-prefix-regexp} evaluates to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13283 @code{nil} or some other value.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13284
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13285 If @code{fill-prefix-regexp} does not have a value, Emacs evaluates
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13286 the else-part of the @code{if} expression and binds @code{parsep} to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13287 its local value. (@code{parsep} is a regular expression that matches
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13288 what separates paragraphs.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13289
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13290 But if @code{fill-prefix-regexp} does have a value, Emacs evaluates
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13291 the then-part of the @code{if} expression and binds @code{parsep} to a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13292 regular expression that includes the @code{fill-prefix-regexp} as part
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13293 of the pattern.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13294
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13295 Specifically, @code{parsep} is set to the original value of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13296 paragraph separate regular expression concatenated with an alternative
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13297 expression that consists of the @code{fill-prefix-regexp} followed by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13298 optional whitespace to the end of the line. The whitespace is defined
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13299 by @w{@code{"[ \t]*$"}}.) The @samp{\\|} defines this portion of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13300 regexp as an alternative to @code{parsep}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13301
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13302 According to a comment in the code, the next local variable,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13303 @code{sp-parstart}, is used for searching, and then the final two,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13304 @code{start} and @code{found-start}, are set to @code{nil}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13305
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13306 Now we get into the body of the @code{let*}. The first part of the body
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13307 of the @code{let*} deals with the case when the function is given a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13308 negative argument and is therefore moving backwards. We will skip this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13309 section.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13310
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13311 @node fwd-para while, , fwd-para let, forward-paragraph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13312 @unnumberedsubsec The forward motion @code{while} loop
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13313
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13314 The second part of the body of the @code{let*} deals with forward
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13315 motion. It is a @code{while} loop that repeats itself so long as the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13316 value of @code{arg} is greater than zero. In the most common use of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13317 the function, the value of the argument is 1, so the body of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13318 @code{while} loop is evaluated exactly once, and the cursor moves
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13319 forward one paragraph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13320
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13321 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13322 (while (and (> arg 0) (not (eobp)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13323
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13324 ;; Move forward over separator lines...
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13325 (while (and (not (eobp))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13326 (progn (move-to-left-margin) (not (eobp)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13327 (looking-at parsep))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13328 (forward-line 1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13329 (unless (eobp) (setq arg (1- arg)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13330 ;; ... and one more line.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13331 (forward-line 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13332
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13333 (if fill-prefix-regexp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13334 ;; There is a fill prefix; it overrides parstart.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13335 (while (and (not (eobp))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13336 (progn (move-to-left-margin) (not (eobp)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13337 (not (looking-at parsep))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13338 (looking-at fill-prefix-regexp))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13339 (forward-line 1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13340
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13341 (while (and (re-search-forward sp-parstart nil 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13342 (progn (setq start (match-beginning 0))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13343 (goto-char start)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13344 (not (eobp)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13345 (progn (move-to-left-margin)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13346 (not (looking-at parsep)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13347 (or (not (looking-at parstart))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13348 (and use-hard-newlines
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13349 (not (get-text-property (1- start) 'hard)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13350 (forward-char 1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13351
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13352 (if (< (point) (point-max))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13353 (goto-char start))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13354 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13355
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13356 This part handles three situations: when point is between paragraphs,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13357 when there is a fill prefix and when there is no fill prefix.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13358
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13359 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13360 The @code{while} loop looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13361
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13362 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13363 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13364 ;; @r{going forwards and not at the end of the buffer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13365 (while (and (> arg 0) (not (eobp)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13366
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13367 ;; @r{between paragraphs}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13368 ;; Move forward over separator lines...
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13369 (while (and (not (eobp))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13370 (progn (move-to-left-margin) (not (eobp)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13371 (looking-at parsep))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13372 (forward-line 1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13373 ;; @r{This decrements the loop}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13374 (unless (eobp) (setq arg (1- arg)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13375 ;; ... and one more line.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13376 (forward-line 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13377 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13378
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13379 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13380 (if fill-prefix-regexp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13381 ;; There is a fill prefix; it overrides parstart;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13382 ;; we go forward line by line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13383 (while (and (not (eobp))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13384 (progn (move-to-left-margin) (not (eobp)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13385 (not (looking-at parsep))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13386 (looking-at fill-prefix-regexp))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13387 (forward-line 1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13388 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13389
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13390 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13391 ;; There is no fill prefix;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13392 ;; we go forward character by character
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13393 (while (and (re-search-forward sp-parstart nil 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13394 (progn (setq start (match-beginning 0))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13395 (goto-char start)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13396 (not (eobp)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13397 (progn (move-to-left-margin)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13398 (not (looking-at parsep)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13399 (or (not (looking-at parstart))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13400 (and use-hard-newlines
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13401 (not (get-text-property (1- start) 'hard)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13402 (forward-char 1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13403 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13404
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13405 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13406 ;; and if there is no fill prefix and if we are not at the end,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13407 ;; go to whatever was found in the regular expression search
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13408 ;; for sp-parstart
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13409 (if (< (point) (point-max))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13410 (goto-char start))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13411 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13412 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13413
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13414 @findex eobp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13415 We can see that this is a decrementing counter @code{while} loop,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13416 using the expression @code{(setq arg (1- arg))} as the decrementer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13417 That expression is not far from the @code{while}, but is hidden in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13418 another Lisp macro, an @code{unless} macro. Unless we are at the end
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13419 of the buffer --- that is what the @code{eobp} function determines; it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13420 is an abbreviation of @samp{End Of Buffer P} --- we decrease the value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13421 of @code{arg} by one.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13422
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13423 (If we are at the end of the buffer, we cannot go forward any more and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13424 the next loop of the @code{while} expression will test false since the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13425 test is an @code{and} with @code{(not (eobp))}. The @code{not}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13426 function means exactly as you expect; it is another name for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13427 @code{null}, a function that returns true when its argument is false.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13428
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13429 Interestingly, the loop count is not decremented until we leave the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13430 space between paragraphs, unless we come to the end of buffer or stop
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13431 seeing the local value of the paragraph separator.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13432
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13433 That second @code{while} also has a @code{(move-to-left-margin)}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13434 expression. The function is self-explanatory. It is inside a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13435 @code{progn} expression and not the last element of its body, so it is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13436 only invoked for its side effect, which is to move point to the left
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13437 margin of the current line.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13438
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13439 @findex looking-at
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13440 The @code{looking-at} function is also self-explanatory; it returns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13441 true if the text after point matches the regular expression given as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13442 its argument.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13443
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13444 The rest of the body of the loop looks difficult at first, but makes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13445 sense as you come to understand it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13446
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13447 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13448 First consider what happens if there is a fill prefix:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13449
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13450 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13451 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13452 (if fill-prefix-regexp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13453 ;; There is a fill prefix; it overrides parstart;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13454 ;; we go forward line by line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13455 (while (and (not (eobp))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13456 (progn (move-to-left-margin) (not (eobp)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13457 (not (looking-at parsep))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13458 (looking-at fill-prefix-regexp))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13459 (forward-line 1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13460 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13461 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13462
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13463 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13464 This expression moves point forward line by line so long
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13465 as four conditions are true:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13466
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13467 @enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13468 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13469 Point is not at the end of the buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13470
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13471 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13472 We can move to the left margin of the text and are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13473 not at the end of the buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13474
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13475 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13476 The text following point does not separate paragraphs.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13477
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13478 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13479 The pattern following point is the fill prefix regular expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13480 @end enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13481
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13482 The last condition may be puzzling, until you remember that point was
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13483 moved to the beginning of the line early in the @code{forward-paragraph}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13484 function. This means that if the text has a fill prefix, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13485 @code{looking-at} function will see it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13486
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13487 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13488 Consider what happens when there is no fill prefix.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13489
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13490 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13491 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13492 (while (and (re-search-forward sp-parstart nil 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13493 (progn (setq start (match-beginning 0))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13494 (goto-char start)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13495 (not (eobp)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13496 (progn (move-to-left-margin)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13497 (not (looking-at parsep)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13498 (or (not (looking-at parstart))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13499 (and use-hard-newlines
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13500 (not (get-text-property (1- start) 'hard)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13501 (forward-char 1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13502 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13503 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13504
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13505 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13506 This @code{while} loop has us searching forward for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13507 @code{sp-parstart}, which is the combination of possible whitespace
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13508 with a the local value of the start of a paragraph or of a paragraph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13509 separator. (The latter two are within an expression starting
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13510 @code{\(?:} so that they are not referenced by the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13511 @code{match-beginning} function.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13512
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13513 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13514 The two expressions,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13515
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13516 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13517 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13518 (setq start (match-beginning 0))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13519 (goto-char start)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13520 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13521 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13522
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13523 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13524 mean go to the start of the text matched by the regular expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13525 search.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13526
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13527 The @code{(match-beginning 0)} expression is new. It returns a number
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13528 specifying the location of the start of the text that was matched by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13529 the last search.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13530
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13531 The @code{match-beginning} function is used here because of a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13532 characteristic of a forward search: a successful forward search,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13533 regardless of whether it is a plain search or a regular expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13534 search, moves point to the end of the text that is found. In this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13535 case, a successful search moves point to the end of the pattern for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13536 @code{sp-parstart}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13537
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13538 However, we want to put point at the end of the current paragraph, not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13539 somewhere else. Indeed, since the search possibly includes the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13540 paragraph separator, point may end up at the beginning of the next one
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13541 unless we use an expression that includes @code{match-beginning}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13542
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13543 @findex match-beginning
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13544 When given an argument of 0, @code{match-beginning} returns the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13545 position that is the start of the text matched by the most recent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13546 search. In this case, the most recent search looks for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13547 @code{sp-parstart}. The @code{(match-beginning 0)} expression returns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13548 the beginning position of that pattern, rather than the end position
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13549 of that pattern.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13550
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13551 (Incidentally, when passed a positive number as an argument, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13552 @code{match-beginning} function returns the location of point at that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13553 parenthesized expression in the last search unless that parenthesized
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13554 expression begins with @code{\(?:}. I don't know why @code{\(?:}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13555 appears here since the argument is 0.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13556
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13557 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13558 The last expression when there is no fill prefix is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13559
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13560 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13561 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13562 (if (< (point) (point-max))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13563 (goto-char start))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13564 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13565 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13566
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13567 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13568 This says that if there is no fill prefix and if we are not at the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13569 end, point should move to the beginning of whatever was found by the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13570 regular expression search for @code{sp-parstart}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13571
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13572 The full definition for the @code{forward-paragraph} function not only
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13573 includes code for going forwards, but also code for going backwards.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13574
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13575 If you are reading this inside of GNU Emacs and you want to see the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13576 whole function, you can type @kbd{C-h f} (@code{describe-function})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13577 and the name of the function. This gives you the function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13578 documentation and the name of the library containing the function's
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13579 source. Place point over the name of the library and press the RET
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13580 key; you will be taken directly to the source. (Be sure to install
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13581 your sources! Without them, you are like a person who tries to drive
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13582 a car with his eyes shut!)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13583
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13584 @node etags, Regexp Review, forward-paragraph, Regexp Search
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13585 @section Create Your Own @file{TAGS} File
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13586 @findex etags
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13587 @cindex @file{TAGS} file, create own
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13588
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13589 Besides @kbd{C-h f} (@code{describe-function}), another way to see the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13590 source of a function is to type @kbd{M-.} (@code{find-tag}) and the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13591 name of the function when prompted for it. This is a good habit to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13592 get into. The @kbd{M-.} (@code{find-tag}) command takes you directly
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13593 to the source for a function, variable, or node. The function depends
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13594 on tags tables to tell it where to go.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13595
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13596 If the @code{find-tag} function first asks you for the name of a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13597 @file{TAGS} table, give it the name of a @file{TAGS} file such as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13598 @file{/usr/local/src/emacs/src/TAGS}. (The exact path to your
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13599 @file{TAGS} file depends on how your copy of Emacs was installed. I
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13600 just told you the location that provides both my C and my Emacs Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13601 sources.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13602
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13603 You can also create your own @file{TAGS} file for directories that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13604 lack one.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13605
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13606 You often need to build and install tags tables yourself. They are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13607 not built automatically. A tags table is called a @file{TAGS} file;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13608 the name is in upper case letters.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13609
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13610 You can create a @file{TAGS} file by calling the @code{etags} program
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13611 that comes as a part of the Emacs distribution. Usually, @code{etags}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13612 is compiled and installed when Emacs is built. (@code{etags} is not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13613 an Emacs Lisp function or a part of Emacs; it is a C program.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13614
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13615 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13616 To create a @file{TAGS} file, first switch to the directory in which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13617 you want to create the file. In Emacs you can do this with the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13618 @kbd{M-x cd} command, or by visiting a file in the directory, or by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13619 listing the directory with @kbd{C-x d} (@code{dired}). Then run the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13620 compile command, with @w{@code{etags *.el}} as the command to execute
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13621
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13622 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13623 M-x compile RET etags *.el RET
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13624 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13625
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13626 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13627 to create a @file{TAGS} file for Emacs Lisp.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13628
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13629 For example, if you have a large number of files in your
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13630 @file{~/emacs} directory, as I do---I have 137 @file{.el} files in it,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13631 of which I load 12---you can create a @file{TAGS} file for the Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13632 Lisp files in that directory.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13633
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13634 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13635 The @code{etags} program takes all the usual shell `wildcards'. For
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13636 example, if you have two directories for which you want a single
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13637 @file{TAGS} file, type @w{@code{etags *.el ../elisp/*.el}}, where
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13638 @file{../elisp/} is the second directory:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13639
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13640 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13641 M-x compile RET etags *.el ../elisp/*.el RET
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13642 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13643
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13644 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13645 Type
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13646
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13647 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13648 M-x compile RET etags --help RET
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13649 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13650
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13651 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13652 to see a list of the options accepted by @code{etags} as well as a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13653 list of supported languages.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13654
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13655 The @code{etags} program handles more than 20 languages, including
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13656 Emacs Lisp, Common Lisp, Scheme, C, C++, Ada, Fortran, HTML, Java,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13657 LaTeX, Pascal, Perl, Postscript, Python, TeX, Texinfo, makefiles, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13658 most assemblers. The program has no switches for specifying the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13659 language; it recognizes the language in an input file according to its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13660 file name and contents.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13661
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13662 @file{etags} is very helpful when you are writing code yourself and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13663 want to refer back to functions you have already written. Just run
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13664 @code{etags} again at intervals as you write new functions, so they
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13665 become part of the @file{TAGS} file.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13666
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13667 If you think an appropriate @file{TAGS} file already exists for what
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13668 you want, but do not know where it is, you can use the @code{locate}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13669 program to attempt to find it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13670
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13671 Type @w{@kbd{M-x locate @key{RET} TAGS @key{RET}}} and Emacs will list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13672 for you the full path names of all your @file{TAGS} files. On my
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13673 system, this command lists 34 @file{TAGS} files. On the other hand, a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13674 `plain vanilla' system I recently installed did not contain any
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13675 @file{TAGS} files.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13676
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13677 If the tags table you want has been created, you can use the @code{M-x
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13678 visit-tags-table} command to specify it. Otherwise, you will need to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13679 create the tag table yourself and then use @code{M-x
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13680 visit-tags-table}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13681
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13682 @subsubheading Building Tags in the Emacs sources
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13683 @cindex Building Tags in the Emacs sources
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13684 @cindex Tags in the Emacs sources
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13685 @findex make tags
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13686
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13687 The GNU Emacs sources come with a @file{Makefile} that contains a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13688 sophisticated @code{etags} command that creates, collects, and merges
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13689 tags tables from all over the Emacs sources and puts the information
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13690 into one @file{TAGS} file in the @file{src/} directory. (The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13691 @file{src/} directory is below the top level of your Emacs directory.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13692
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13693 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13694 To build this @file{TAGS} file, go to the top level of your Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13695 source directory and run the compile command @code{make tags}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13696
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13697 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13698 M-x compile RET make tags RET
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13699 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13700
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13701 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13702 (The @code{make tags} command works well with the GNU Emacs sources,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13703 as well as with some other source packages.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13704
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13705 For more information, see @ref{Tags, , Tag Tables, emacs, The GNU Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13706 Manual}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13707
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13708 @node Regexp Review, re-search Exercises, etags, Regexp Search
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13709 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13710 @section Review
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13711
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13712 Here is a brief summary of some recently introduced functions.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13713
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13714 @table @code
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13715 @item while
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13716 Repeatedly evaluate the body of the expression so long as the first
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13717 element of the body tests true. Then return @code{nil}. (The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13718 expression is evaluated only for its side effects.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13719
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13720 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13721 For example:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13722
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13723 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13724 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13725 (let ((foo 2))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13726 (while (> foo 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13727 (insert (format "foo is %d.\n" foo))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13728 (setq foo (1- foo))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13729
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13730 @result{} foo is 2.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13731 foo is 1.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13732 nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13733 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13734 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13735
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13736 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13737 (The @code{insert} function inserts its arguments at point; the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13738 @code{format} function returns a string formatted from its arguments
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13739 the way @code{message} formats its arguments; @code{\n} produces a new
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13740 line.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13741
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13742 @item re-search-forward
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13743 Search for a pattern, and if the pattern is found, move point to rest
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13744 just after it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13745
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13746 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13747 Takes four arguments, like @code{search-forward}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13748
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13749 @enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13750 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13751 A regular expression that specifies the pattern to search for.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13752 (Remember to put quotation marks around this argument!)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13753
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13754 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13755 Optionally, the limit of the search.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13756
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13757 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13758 Optionally, what to do if the search fails, return @code{nil} or an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13759 error message.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13760
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13761 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13762 Optionally, how many times to repeat the search; if negative, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13763 search goes backwards.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13764 @end enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13765
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13766 @item let*
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13767 Bind some variables locally to particular values,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13768 and then evaluate the remaining arguments, returning the value of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13769 last one. While binding the local variables, use the local values of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13770 variables bound earlier, if any.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13771
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13772 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13773 For example:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13774
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13775 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13776 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13777 (let* ((foo 7)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13778 (bar (* 3 foo)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13779 (message "`bar' is %d." bar))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13780 @result{} `bar' is 21.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13781 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13782 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13783
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13784 @item match-beginning
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13785 Return the position of the start of the text found by the last regular
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13786 expression search.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13787
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13788 @item looking-at
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13789 Return @code{t} for true if the text after point matches the argument,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13790 which should be a regular expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13791
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13792 @item eobp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13793 Return @code{t} for true if point is at the end of the accessible part
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13794 of a buffer. The end of the accessible part is the end of the buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13795 if the buffer is not narrowed; it is the end of the narrowed part if
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13796 the buffer is narrowed.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13797 @end table
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13798
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13799 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13800 @node re-search Exercises, , Regexp Review, Regexp Search
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13801 @section Exercises with @code{re-search-forward}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13802
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13803 @itemize @bullet
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13804 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13805 Write a function to search for a regular expression that matches two
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13806 or more blank lines in sequence.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13807
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13808 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13809 Write a function to search for duplicated words, such as `the the'.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13810 @xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13811 Manual}, for information on how to write a regexp (a regular
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13812 expression) to match a string that is composed of two identical
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13813 halves. You can devise several regexps; some are better than others.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13814 The function I use is described in an appendix, along with several
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13815 regexps. @xref{the-the, , @code{the-the} Duplicated Words Function}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13816 @end itemize
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13817
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13818 @node Counting Words, Words in a defun, Regexp Search, Top
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13819 @chapter Counting: Repetition and Regexps
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13820 @cindex Repetition for word counting
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13821 @cindex Regular expressions for word counting
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13822
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13823 Repetition and regular expression searches are powerful tools that you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13824 often use when you write code in Emacs Lisp. This chapter illustrates
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13825 the use of regular expression searches through the construction of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13826 word count commands using @code{while} loops and recursion.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13827
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13828 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13829 * Why Count Words::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13830 * count-words-region:: Use a regexp, but find a problem.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13831 * recursive-count-words:: Start with case of no words in region.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13832 * Counting Exercise::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13833 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13834
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13835 @node Why Count Words, count-words-region, Counting Words, Counting Words
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13836 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13837 @unnumberedsec Counting words
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13838 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13839
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13840 The standard Emacs distribution contains a function for counting the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13841 number of lines within a region. However, there is no corresponding
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13842 function for counting words.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13843
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13844 Certain types of writing ask you to count words. Thus, if you write
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13845 an essay, you may be limited to 800 words; if you write a novel, you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13846 may discipline yourself to write 1000 words a day. It seems odd to me
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13847 that Emacs lacks a word count command. Perhaps people use Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13848 mostly for code or types of documentation that do not require word
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13849 counts; or perhaps they restrict themselves to the operating system
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13850 word count command, @code{wc}. Alternatively, people may follow
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13851 the publishers' convention and compute a word count by dividing the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13852 number of characters in a document by five. In any event, here are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13853 commands to count words.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13854
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13855 @node count-words-region, recursive-count-words, Why Count Words, Counting Words
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13856 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13857 @section The @code{count-words-region} Function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13858 @findex count-words-region
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13859
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13860 A word count command could count words in a line, paragraph, region,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13861 or buffer. What should the command cover? You could design the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13862 command to count the number of words in a complete buffer. However,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13863 the Emacs tradition encourages flexibility---you may want to count
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13864 words in just a section, rather than all of a buffer. So it makes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13865 more sense to design the command to count the number of words in a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13866 region. Once you have a @code{count-words-region} command, you can,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13867 if you wish, count words in a whole buffer by marking it with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13868 @w{@kbd{C-x h}} (@code{mark-whole-buffer}).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13869
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13870 Clearly, counting words is a repetitive act: starting from the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13871 beginning of the region, you count the first word, then the second
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13872 word, then the third word, and so on, until you reach the end of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13873 region. This means that word counting is ideally suited to recursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13874 or to a @code{while} loop.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13875
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13876 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13877 * Design count-words-region:: The definition using a @code{while} loop.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13878 * Whitespace Bug:: The Whitespace Bug in @code{count-words-region}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13879 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13880
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13881 @node Design count-words-region, Whitespace Bug, count-words-region, count-words-region
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13882 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13883 @unnumberedsubsec Designing @code{count-words-region}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13884 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13885
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13886 First, we will implement the word count command with a @code{while}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13887 loop, then with recursion. The command will, of course, be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13888 interactive.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13889
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13890 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13891 The template for an interactive function definition is, as always:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13892
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13893 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13894 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13895 (defun @var{name-of-function} (@var{argument-list})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13896 "@var{documentation}@dots{}"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13897 (@var{interactive-expression}@dots{})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13898 @var{body}@dots{})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13899 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13900 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13901
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13902 What we need to do is fill in the slots.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13903
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13904 The name of the function should be self-explanatory and similar to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13905 existing @code{count-lines-region} name. This makes the name easier
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13906 to remember. @code{count-words-region} is a good choice.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13907
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13908 The function counts words within a region. This means that the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13909 argument list must contain symbols that are bound to the two
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13910 positions, the beginning and end of the region. These two positions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13911 can be called @samp{beginning} and @samp{end} respectively. The first
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13912 line of the documentation should be a single sentence, since that is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13913 all that is printed as documentation by a command such as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13914 @code{apropos}. The interactive expression will be of the form
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13915 @samp{(interactive "r")}, since that will cause Emacs to pass the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13916 beginning and end of the region to the function's argument list. All
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13917 this is routine.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13918
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13919 The body of the function needs to be written to do three tasks:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13920 first, to set up conditions under which the @code{while} loop can
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13921 count words, second, to run the @code{while} loop, and third, to send
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13922 a message to the user.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13923
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13924 When a user calls @code{count-words-region}, point may be at the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13925 beginning or the end of the region. However, the counting process
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13926 must start at the beginning of the region. This means we will want
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13927 to put point there if it is not already there. Executing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13928 @code{(goto-char beginning)} ensures this. Of course, we will want to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13929 return point to its expected position when the function finishes its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13930 work. For this reason, the body must be enclosed in a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13931 @code{save-excursion} expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13932
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13933 The central part of the body of the function consists of a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13934 @code{while} loop in which one expression jumps point forward word by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13935 word, and another expression counts those jumps. The true-or-false-test
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13936 of the @code{while} loop should test true so long as point should jump
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13937 forward, and false when point is at the end of the region.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13938
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13939 We could use @code{(forward-word 1)} as the expression for moving point
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13940 forward word by word, but it is easier to see what Emacs identifies as a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13941 `word' if we use a regular expression search.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13942
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13943 A regular expression search that finds the pattern for which it is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13944 searching leaves point after the last character matched. This means
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13945 that a succession of successful word searches will move point forward
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13946 word by word.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13947
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13948 As a practical matter, we want the regular expression search to jump
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13949 over whitespace and punctuation between words as well as over the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13950 words themselves. A regexp that refuses to jump over interword
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13951 whitespace would never jump more than one word! This means that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13952 the regexp should include the whitespace and punctuation that follows
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13953 a word, if any, as well as the word itself. (A word may end a buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13954 and not have any following whitespace or punctuation, so that part of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13955 the regexp must be optional.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13956
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13957 Thus, what we want for the regexp is a pattern defining one or more
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13958 word constituent characters followed, optionally, by one or more
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13959 characters that are not word constituents. The regular expression for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13960 this is:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13961
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13962 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13963 \w+\W*
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13964 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13965
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13966 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13967 The buffer's syntax table determines which characters are and are not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13968 word constituents. (@xref{Syntax, , What Constitutes a Word or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13969 Symbol?}, for more about syntax. Also, see @ref{Syntax, Syntax, The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13970 Syntax Table, emacs, The GNU Emacs Manual}, and @ref{Syntax Tables, ,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13971 Syntax Tables, elisp, The GNU Emacs Lisp Reference Manual}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13972
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13973 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13974 The search expression looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13975
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13976 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13977 (re-search-forward "\\w+\\W*")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13978 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13979
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13980 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13981 (Note that paired backslashes precede the @samp{w} and @samp{W}. A
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13982 single backslash has special meaning to the Emacs Lisp interpreter.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13983 It indicates that the following character is interpreted differently
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13984 than usual. For example, the two characters, @samp{\n}, stand for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13985 @samp{newline}, rather than for a backslash followed by @samp{n}. Two
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13986 backslashes in a row stand for an ordinary, `unspecial' backslash, so
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13987 Emacs Lisp interpreter ends of seeing a single backslash followed by a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13988 letter. So it discovers the letter is special.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13989
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13990 We need a counter to count how many words there are; this variable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13991 must first be set to 0 and then incremented each time Emacs goes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13992 around the @code{while} loop. The incrementing expression is simply:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13993
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13994 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13995 (setq count (1+ count))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13996 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13997
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13998 Finally, we want to tell the user how many words there are in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13999 region. The @code{message} function is intended for presenting this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14000 kind of information to the user. The message has to be phrased so
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14001 that it reads properly regardless of how many words there are in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14002 region: we don't want to say that ``there are 1 words in the region''.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14003 The conflict between singular and plural is ungrammatical. We can
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14004 solve this problem by using a conditional expression that evaluates
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14005 different messages depending on the number of words in the region.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14006 There are three possibilities: no words in the region, one word in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14007 region, and more than one word. This means that the @code{cond}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14008 special form is appropriate.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14009
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14010 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14011 All this leads to the following function definition:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14012
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14013 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14014 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14015 ;;; @r{First version; has bugs!}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14016 (defun count-words-region (beginning end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14017 "Print number of words in the region.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14018 Words are defined as at least one word-constituent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14019 character followed by at least one character that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14020 is not a word-constituent. The buffer's syntax
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14021 table determines which characters these are."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14022 (interactive "r")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14023 (message "Counting words in region ... ")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14024 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14025
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14026 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14027 ;;; @r{1. Set up appropriate conditions.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14028 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14029 (goto-char beginning)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14030 (let ((count 0))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14031 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14032
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14033 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14034 ;;; @r{2. Run the} while @r{loop.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14035 (while (< (point) end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14036 (re-search-forward "\\w+\\W*")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14037 (setq count (1+ count)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14038 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14039
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14040 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14041 ;;; @r{3. Send a message to the user.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14042 (cond ((zerop count)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14043 (message
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14044 "The region does NOT have any words."))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14045 ((= 1 count)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14046 (message
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14047 "The region has 1 word."))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14048 (t
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14049 (message
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14050 "The region has %d words." count))))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14051 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14052 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14053
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14054 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14055 As written, the function works, but not in all circumstances.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14056
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14057 @node Whitespace Bug, , Design count-words-region, count-words-region
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14058 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14059 @subsection The Whitespace Bug in @code{count-words-region}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14060
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14061 The @code{count-words-region} command described in the preceding
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14062 section has two bugs, or rather, one bug with two manifestations.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14063 First, if you mark a region containing only whitespace in the middle
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14064 of some text, the @code{count-words-region} command tells you that the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14065 region contains one word! Second, if you mark a region containing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14066 only whitespace at the end of the buffer or the accessible portion of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14067 a narrowed buffer, the command displays an error message that looks
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14068 like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14069
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14070 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14071 Search failed: "\\w+\\W*"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14072 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14073
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14074 If you are reading this in Info in GNU Emacs, you can test for these
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14075 bugs yourself.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14076
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14077 First, evaluate the function in the usual manner to install it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14078 @ifinfo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14079 Here is a copy of the definition. Place your cursor after the closing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14080 parenthesis and type @kbd{C-x C-e} to install it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14081
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14082 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14083 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14084 ;; @r{First version; has bugs!}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14085 (defun count-words-region (beginning end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14086 "Print number of words in the region.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14087 Words are defined as at least one word-constituent character followed
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14088 by at least one character that is not a word-constituent. The buffer's
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14089 syntax table determines which characters these are."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14090 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14091 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14092 (interactive "r")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14093 (message "Counting words in region ... ")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14094 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14095
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14096 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14097 ;;; @r{1. Set up appropriate conditions.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14098 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14099 (goto-char beginning)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14100 (let ((count 0))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14101 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14102
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14103 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14104 ;;; @r{2. Run the} while @r{loop.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14105 (while (< (point) end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14106 (re-search-forward "\\w+\\W*")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14107 (setq count (1+ count)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14108 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14109
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14110 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14111 ;;; @r{3. Send a message to the user.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14112 (cond ((zerop count)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14113 (message "The region does NOT have any words."))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14114 ((= 1 count) (message "The region has 1 word."))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14115 (t (message "The region has %d words." count))))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14116 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14117 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14118 @end ifinfo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14119
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14120 @need 1000
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14121 If you wish, you can also install this keybinding by evaluating it:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14122
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14123 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14124 (global-set-key "\C-c=" 'count-words-region)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14125 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14126
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14127 To conduct the first test, set mark and point to the beginning and end
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14128 of the following line and then type @kbd{C-c =} (or @kbd{M-x
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14129 count-words-region} if you have not bound @kbd{C-c =}):
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14130
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14131 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14132 one two three
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14133 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14134
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14135 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14136 Emacs will tell you, correctly, that the region has three words.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14137
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14138 Repeat the test, but place mark at the beginning of the line and place
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14139 point just @emph{before} the word @samp{one}. Again type the command
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14140 @kbd{C-c =} (or @kbd{M-x count-words-region}). Emacs should tell you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14141 that the region has no words, since it is composed only of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14142 whitespace at the beginning of the line. But instead Emacs tells you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14143 that the region has one word!
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14144
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14145 For the third test, copy the sample line to the end of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14146 @file{*scratch*} buffer and then type several spaces at the end of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14147 line. Place mark right after the word @samp{three} and point at the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14148 end of line. (The end of the line will be the end of the buffer.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14149 Type @kbd{C-c =} (or @kbd{M-x count-words-region}) as you did before.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14150 Again, Emacs should tell you that the region has no words, since it is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14151 composed only of the whitespace at the end of the line. Instead,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14152 Emacs displays an error message saying @samp{Search failed}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14153
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14154 The two bugs stem from the same problem.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14155
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14156 Consider the first manifestation of the bug, in which the command
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14157 tells you that the whitespace at the beginning of the line contains
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14158 one word. What happens is this: The @code{M-x count-words-region}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14159 command moves point to the beginning of the region. The @code{while}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14160 tests whether the value of point is smaller than the value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14161 @code{end}, which it is. Consequently, the regular expression search
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14162 looks for and finds the first word. It leaves point after the word.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14163 @code{count} is set to one. The @code{while} loop repeats; but this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14164 time the value of point is larger than the value of @code{end}, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14165 loop is exited; and the function displays a message saying the number
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14166 of words in the region is one. In brief, the regular expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14167 search looks for and finds the word even though it is outside
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14168 the marked region.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14169
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14170 In the second manifestation of the bug, the region is whitespace at
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14171 the end of the buffer. Emacs says @samp{Search failed}. What happens
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14172 is that the true-or-false-test in the @code{while} loop tests true, so
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14173 the search expression is executed. But since there are no more words
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14174 in the buffer, the search fails.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14175
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14176 In both manifestations of the bug, the search extends or attempts to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14177 extend outside of the region.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14178
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14179 The solution is to limit the search to the region---this is a fairly
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14180 simple action, but as you may have come to expect, it is not quite as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14181 simple as you might think.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14182
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14183 As we have seen, the @code{re-search-forward} function takes a search
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14184 pattern as its first argument. But in addition to this first,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14185 mandatory argument, it accepts three optional arguments. The optional
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14186 second argument bounds the search. The optional third argument, if
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14187 @code{t}, causes the function to return @code{nil} rather than signal
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14188 an error if the search fails. The optional fourth argument is a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14189 repeat count. (In Emacs, you can see a function's documentation by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14190 typing @kbd{C-h f}, the name of the function, and then @key{RET}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14191
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14192 In the @code{count-words-region} definition, the value of the end of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14193 the region is held by the variable @code{end} which is passed as an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14194 argument to the function. Thus, we can add @code{end} as an argument
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14195 to the regular expression search expression:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14196
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14197 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14198 (re-search-forward "\\w+\\W*" end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14199 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14201 However, if you make only this change to the @code{count-words-region}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14202 definition and then test the new version of the definition on a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14203 stretch of whitespace, you will receive an error message saying
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14204 @samp{Search failed}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14205
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14206 What happens is this: the search is limited to the region, and fails
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14207 as you expect because there are no word-constituent characters in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14208 region. Since it fails, we receive an error message. But we do not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14209 want to receive an error message in this case; we want to receive the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14210 message that "The region does NOT have any words."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14211
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14212 The solution to this problem is to provide @code{re-search-forward}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14213 with a third argument of @code{t}, which causes the function to return
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14214 @code{nil} rather than signal an error if the search fails.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14215
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14216 However, if you make this change and try it, you will see the message
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14217 ``Counting words in region ... '' and @dots{} you will keep on seeing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14218 that message @dots{}, until you type @kbd{C-g} (@code{keyboard-quit}).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14219
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14220 Here is what happens: the search is limited to the region, as before,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14221 and it fails because there are no word-constituent characters in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14222 region, as expected. Consequently, the @code{re-search-forward}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14223 expression returns @code{nil}. It does nothing else. In particular,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14224 it does not move point, which it does as a side effect if it finds the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14225 search target. After the @code{re-search-forward} expression returns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14226 @code{nil}, the next expression in the @code{while} loop is evaluated.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14227 This expression increments the count. Then the loop repeats. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14228 true-or-false-test tests true because the value of point is still less
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14229 than the value of end, since the @code{re-search-forward} expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14230 did not move point. @dots{} and the cycle repeats @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14231
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14232 The @code{count-words-region} definition requires yet another
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14233 modification, to cause the true-or-false-test of the @code{while} loop
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14234 to test false if the search fails. Put another way, there are two
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14235 conditions that must be satisfied in the true-or-false-test before the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14236 word count variable is incremented: point must still be within the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14237 region and the search expression must have found a word to count.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14238
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14239 Since both the first condition and the second condition must be true
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14240 together, the two expressions, the region test and the search
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14241 expression, can be joined with an @code{and} special form and embedded in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14242 the @code{while} loop as the true-or-false-test, like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14243
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14244 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14245 (and (< (point) end) (re-search-forward "\\w+\\W*" end t))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14246 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14247
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14248 @c colon in printed section title causes problem in Info cross reference
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14249 @c also trouble with an overfull hbox
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14250 @iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14251 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14252 (For information about @code{and}, see
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14253 @ref{kill-new function, , The @code{kill-new} function}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14254 @end iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14255 @ifinfo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14256 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14257 (@xref{kill-new function, , The @code{kill-new} function}, for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14258 information about @code{and}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14259 @end ifinfo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14260
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14261 The @code{re-search-forward} expression returns @code{t} if the search
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14262 succeeds and as a side effect moves point. Consequently, as words are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14263 found, point is moved through the region. When the search expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14264 fails to find another word, or when point reaches the end of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14265 region, the true-or-false-test tests false, the @code{while} loop
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14266 exits, and the @code{count-words-region} function displays one or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14267 other of its messages.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14268
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14269 After incorporating these final changes, the @code{count-words-region}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14270 works without bugs (or at least, without bugs that I have found!).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14271 Here is what it looks like:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14272
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14273 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14274 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14275 ;;; @r{Final version:} @code{while}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14276 (defun count-words-region (beginning end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14277 "Print number of words in the region."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14278 (interactive "r")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14279 (message "Counting words in region ... ")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14280 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14281
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14282 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14283 ;;; @r{1. Set up appropriate conditions.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14284 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14285 (let ((count 0))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14286 (goto-char beginning)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14287 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14288
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14289 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14290 ;;; @r{2. Run the} while @r{loop.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14291 (while (and (< (point) end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14292 (re-search-forward "\\w+\\W*" end t))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14293 (setq count (1+ count)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14294 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14295
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14296 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14297 ;;; @r{3. Send a message to the user.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14298 (cond ((zerop count)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14299 (message
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14300 "The region does NOT have any words."))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14301 ((= 1 count)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14302 (message
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14303 "The region has 1 word."))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14304 (t
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14305 (message
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14306 "The region has %d words." count))))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14307 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14308 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14309
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14310 @node recursive-count-words, Counting Exercise, count-words-region, Counting Words
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14311 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14312 @section Count Words Recursively
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14313 @cindex Count words recursively
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14314 @cindex Recursively counting words
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14315 @cindex Words, counted recursively
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14316
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14317 You can write the function for counting words recursively as well as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14318 with a @code{while} loop. Let's see how this is done.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14319
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14320 First, we need to recognize that the @code{count-words-region}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14321 function has three jobs: it sets up the appropriate conditions for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14322 counting to occur; it counts the words in the region; and it sends a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14323 message to the user telling how many words there are.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14324
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14325 If we write a single recursive function to do everything, we will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14326 receive a message for every recursive call. If the region contains 13
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14327 words, we will receive thirteen messages, one right after the other.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14328 We don't want this! Instead, we must write two functions to do the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14329 job, one of which (the recursive function) will be used inside of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14330 other. One function will set up the conditions and display the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14331 message; the other will return the word count.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14332
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14333 Let us start with the function that causes the message to be displayed.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14334 We can continue to call this @code{count-words-region}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14335
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14336 This is the function that the user will call. It will be interactive.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14337 Indeed, it will be similar to our previous versions of this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14338 function, except that it will call @code{recursive-count-words} to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14339 determine how many words are in the region.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14340
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14341 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14342 We can readily construct a template for this function, based on our
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14343 previous versions:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14344
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14345 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14346 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14347 ;; @r{Recursive version; uses regular expression search}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14348 (defun count-words-region (beginning end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14349 "@var{documentation}@dots{}"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14350 (@var{interactive-expression}@dots{})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14351 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14352 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14353
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14354 ;;; @r{1. Set up appropriate conditions.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14355 (@var{explanatory message})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14356 (@var{set-up functions}@dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14357 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14358 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14359
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14360 ;;; @r{2. Count the words.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14361 @var{recursive call}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14362 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14363 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14364
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14365 ;;; @r{3. Send a message to the user.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14366 @var{message providing word count}))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14367 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14368 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14369
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14370 The definition looks straightforward, except that somehow the count
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14371 returned by the recursive call must be passed to the message
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14372 displaying the word count. A little thought suggests that this can be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14373 done by making use of a @code{let} expression: we can bind a variable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14374 in the varlist of a @code{let} expression to the number of words in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14375 the region, as returned by the recursive call; and then the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14376 @code{cond} expression, using binding, can display the value to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14377 user.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14378
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14379 Often, one thinks of the binding within a @code{let} expression as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14380 somehow secondary to the `primary' work of a function. But in this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14381 case, what you might consider the `primary' job of the function,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14382 counting words, is done within the @code{let} expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14383
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14384 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14385 Using @code{let}, the function definition looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14386
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14387 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14388 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14389 (defun count-words-region (beginning end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14390 "Print number of words in the region."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14391 (interactive "r")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14392 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14393
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14394 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14395 ;;; @r{1. Set up appropriate conditions.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14396 (message "Counting words in region ... ")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14397 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14398 (goto-char beginning)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14399 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14400
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14401 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14402 ;;; @r{2. Count the words.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14403 (let ((count (recursive-count-words end)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14404 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14405
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14406 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14407 ;;; @r{3. Send a message to the user.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14408 (cond ((zerop count)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14409 (message
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14410 "The region does NOT have any words."))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14411 ((= 1 count)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14412 (message
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14413 "The region has 1 word."))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14414 (t
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14415 (message
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14416 "The region has %d words." count))))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14417 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14418 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14419
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14420 Next, we need to write the recursive counting function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14421
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14422 A recursive function has at least three parts: the `do-again-test', the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14423 `next-step-expression', and the recursive call.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14424
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14425 The do-again-test determines whether the function will or will not be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14426 called again. Since we are counting words in a region and can use a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14427 function that moves point forward for every word, the do-again-test
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14428 can check whether point is still within the region. The do-again-test
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14429 should find the value of point and determine whether point is before,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14430 at, or after the value of the end of the region. We can use the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14431 @code{point} function to locate point. Clearly, we must pass the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14432 value of the end of the region to the recursive counting function as an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14433 argument.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14434
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14435 In addition, the do-again-test should also test whether the search finds a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14436 word. If it does not, the function should not call itself again.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14437
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14438 The next-step-expression changes a value so that when the recursive
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14439 function is supposed to stop calling itself, it stops. More
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14440 precisely, the next-step-expression changes a value so that at the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14441 right time, the do-again-test stops the recursive function from
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14442 calling itself again. In this case, the next-step-expression can be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14443 the expression that moves point forward, word by word.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14444
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14445 The third part of a recursive function is the recursive call.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14446
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14447 Somewhere, also, we also need a part that does the `work' of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14448 function, a part that does the counting. A vital part!
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14449
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14450 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14451 But already, we have an outline of the recursive counting function:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14452
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14453 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14454 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14455 (defun recursive-count-words (region-end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14456 "@var{documentation}@dots{}"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14457 @var{do-again-test}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14458 @var{next-step-expression}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14459 @var{recursive call})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14460 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14461 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14462
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14463 Now we need to fill in the slots. Let's start with the simplest cases
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14464 first: if point is at or beyond the end of the region, there cannot
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14465 be any words in the region, so the function should return zero.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14466 Likewise, if the search fails, there are no words to count, so the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14467 function should return zero.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14468
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14469 On the other hand, if point is within the region and the search
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14470 succeeds, the function should call itself again.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14471
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14472 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14473 Thus, the do-again-test should look like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14474
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14475 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14476 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14477 (and (< (point) region-end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14478 (re-search-forward "\\w+\\W*" region-end t))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14479 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14480 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14481
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14482 Note that the search expression is part of the do-again-test---the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14483 function returns @code{t} if its search succeeds and @code{nil} if it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14484 fails. (@xref{Whitespace Bug, , The Whitespace Bug in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14485 @code{count-words-region}}, for an explanation of how
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14486 @code{re-search-forward} works.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14487
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14488 The do-again-test is the true-or-false test of an @code{if} clause.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14489 Clearly, if the do-again-test succeeds, the then-part of the @code{if}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14490 clause should call the function again; but if it fails, the else-part
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14491 should return zero since either point is outside the region or the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14492 search failed because there were no words to find.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14493
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14494 But before considering the recursive call, we need to consider the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14495 next-step-expression. What is it? Interestingly, it is the search
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14496 part of the do-again-test.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14497
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14498 In addition to returning @code{t} or @code{nil} for the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14499 do-again-test, @code{re-search-forward} moves point forward as a side
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14500 effect of a successful search. This is the action that changes the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14501 value of point so that the recursive function stops calling itself
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14502 when point completes its movement through the region. Consequently,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14503 the @code{re-search-forward} expression is the next-step-expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14504
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14505 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14506 In outline, then, the body of the @code{recursive-count-words}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14507 function looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14508
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14509 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14510 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14511 (if @var{do-again-test-and-next-step-combined}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14512 ;; @r{then}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14513 @var{recursive-call-returning-count}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14514 ;; @r{else}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14515 @var{return-zero})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14516 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14517 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14518
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14519 How to incorporate the mechanism that counts?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14520
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14521 If you are not used to writing recursive functions, a question like
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14522 this can be troublesome. But it can and should be approached
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14523 systematically.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14524
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14525 We know that the counting mechanism should be associated in some way
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14526 with the recursive call. Indeed, since the next-step-expression moves
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14527 point forward by one word, and since a recursive call is made for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14528 each word, the counting mechanism must be an expression that adds one
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14529 to the value returned by a call to @code{recursive-count-words}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14530
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14531 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14532 Consider several cases:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14533
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14534 @itemize @bullet
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14535 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14536 If there are two words in the region, the function should return
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14537 a value resulting from adding one to the value returned when it counts
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14538 the first word, plus the number returned when it counts the remaining
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14539 words in the region, which in this case is one.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14540
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14541 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14542 If there is one word in the region, the function should return
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14543 a value resulting from adding one to the value returned when it counts
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14544 that word, plus the number returned when it counts the remaining
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14545 words in the region, which in this case is zero.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14546
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14547 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14548 If there are no words in the region, the function should return zero.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14549 @end itemize
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14550
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14551 From the sketch we can see that the else-part of the @code{if} returns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14552 zero for the case of no words. This means that the then-part of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14553 @code{if} must return a value resulting from adding one to the value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14554 returned from a count of the remaining words.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14555
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14556 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14557 The expression will look like this, where @code{1+} is a function that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14558 adds one to its argument.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14559
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14560 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14561 (1+ (recursive-count-words region-end))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14562 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14563
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14564 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14565 The whole @code{recursive-count-words} function will then look like
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14566 this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14567
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14568 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14569 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14570 (defun recursive-count-words (region-end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14571 "@var{documentation}@dots{}"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14572
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14573 ;;; @r{1. do-again-test}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14574 (if (and (< (point) region-end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14575 (re-search-forward "\\w+\\W*" region-end t))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14576 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14577
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14578 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14579 ;;; @r{2. then-part: the recursive call}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14580 (1+ (recursive-count-words region-end))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14581
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14582 ;;; @r{3. else-part}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14583 0))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14584 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14585 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14586
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14587 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14588 Let's examine how this works:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14589
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14590 If there are no words in the region, the else part of the @code{if}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14591 expression is evaluated and consequently the function returns zero.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14592
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14593 If there is one word in the region, the value of point is less than
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14594 the value of @code{region-end} and the search succeeds. In this case,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14595 the true-or-false-test of the @code{if} expression tests true, and the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14596 then-part of the @code{if} expression is evaluated. The counting
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14597 expression is evaluated. This expression returns a value (which will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14598 be the value returned by the whole function) that is the sum of one
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14599 added to the value returned by a recursive call.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14600
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14601 Meanwhile, the next-step-expression has caused point to jump over the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14602 first (and in this case only) word in the region. This means that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14603 when @code{(recursive-count-words region-end)} is evaluated a second
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14604 time, as a result of the recursive call, the value of point will be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14605 equal to or greater than the value of region end. So this time,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14606 @code{recursive-count-words} will return zero. The zero will be added
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14607 to one, and the original evaluation of @code{recursive-count-words}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14608 will return one plus zero, which is one, which is the correct amount.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14609
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14610 Clearly, if there are two words in the region, the first call to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14611 @code{recursive-count-words} returns one added to the value returned
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14612 by calling @code{recursive-count-words} on a region containing the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14613 remaining word---that is, it adds one to one, producing two, which is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14614 the correct amount.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14615
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14616 Similarly, if there are three words in the region, the first call to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14617 @code{recursive-count-words} returns one added to the value returned
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14618 by calling @code{recursive-count-words} on a region containing the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14619 remaining two words---and so on and so on.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14620
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14621 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14622 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14623 With full documentation the two functions look like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14624
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14625 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14626 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14627 The recursive function:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14628
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14629 @findex recursive-count-words
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14630 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14631 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14632 (defun recursive-count-words (region-end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14633 "Number of words between point and REGION-END."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14634 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14635
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14636 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14637 ;;; @r{1. do-again-test}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14638 (if (and (< (point) region-end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14639 (re-search-forward "\\w+\\W*" region-end t))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14640 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14641
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14642 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14643 ;;; @r{2. then-part: the recursive call}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14644 (1+ (recursive-count-words region-end))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14645
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14646 ;;; @r{3. else-part}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14647 0))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14648 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14649 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14650
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14651 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14652 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14653 The wrapper:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14654
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14655 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14656 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14657 ;;; @r{Recursive version}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14658 (defun count-words-region (beginning end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14659 "Print number of words in the region.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14660 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14661
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14662 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14663 Words are defined as at least one word-constituent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14664 character followed by at least one character that is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14665 not a word-constituent. The buffer's syntax table
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14666 determines which characters these are."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14667 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14668 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14669 (interactive "r")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14670 (message "Counting words in region ... ")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14671 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14672 (goto-char beginning)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14673 (let ((count (recursive-count-words end)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14674 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14675 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14676 (cond ((zerop count)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14677 (message
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14678 "The region does NOT have any words."))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14679 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14680 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14681 ((= 1 count)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14682 (message "The region has 1 word."))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14683 (t
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14684 (message
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14685 "The region has %d words." count))))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14686 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14687 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14688
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14689 @node Counting Exercise, , recursive-count-words, Counting Words
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14690 @section Exercise: Counting Punctuation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14691
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14692 Using a @code{while} loop, write a function to count the number of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14693 punctuation marks in a region---period, comma, semicolon, colon,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14694 exclamation mark, and question mark. Do the same using recursion.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14695
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14696 @node Words in a defun, Readying a Graph, Counting Words, Top
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14697 @chapter Counting Words in a @code{defun}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14698 @cindex Counting words in a @code{defun}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14699 @cindex Word counting in a @code{defun}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14700
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14701 Our next project is to count the number of words in a function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14702 definition. Clearly, this can be done using some variant of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14703 @code{count-word-region}. @xref{Counting Words, , Counting Words:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14704 Repetition and Regexps}. If we are just going to count the words in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14705 one definition, it is easy enough to mark the definition with the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14706 @kbd{C-M-h} (@code{mark-defun}) command, and then call
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14707 @code{count-word-region}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14708
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14709 However, I am more ambitious: I want to count the words and symbols in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14710 every definition in the Emacs sources and then print a graph that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14711 shows how many functions there are of each length: how many contain 40
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14712 to 49 words or symbols, how many contain 50 to 59 words or symbols,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14713 and so on. I have often been curious how long a typical function is,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14714 and this will tell.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14715
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14716 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14717 * Divide and Conquer::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14718 * Words and Symbols:: What to count?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14719 * Syntax:: What constitutes a word or symbol?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14720 * count-words-in-defun:: Very like @code{count-words}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14721 * Several defuns:: Counting several defuns in a file.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14722 * Find a File:: Do you want to look at a file?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14723 * lengths-list-file:: A list of the lengths of many definitions.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14724 * Several files:: Counting in definitions in different files.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14725 * Several files recursively:: Recursively counting in different files.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14726 * Prepare the data:: Prepare the data for display in a graph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14727 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14728
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14729 @node Divide and Conquer, Words and Symbols, Words in a defun, Words in a defun
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14730 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14731 @unnumberedsec Divide and Conquer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14732 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14733
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14734 Described in one phrase, the histogram project is daunting; but
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14735 divided into numerous small steps, each of which we can take one at a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14736 time, the project becomes less fearsome. Let us consider what the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14737 steps must be:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14738
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14739 @itemize @bullet
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14740 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14741 First, write a function to count the words in one definition. This
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14742 includes the problem of handling symbols as well as words.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14743
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14744 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14745 Second, write a function to list the numbers of words in each function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14746 in a file. This function can use the @code{count-words-in-defun}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14747 function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14748
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14749 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14750 Third, write a function to list the numbers of words in each function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14751 in each of several files. This entails automatically finding the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14752 various files, switching to them, and counting the words in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14753 definitions within them.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14754
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14755 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14756 Fourth, write a function to convert the list of numbers that we
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14757 created in step three to a form that will be suitable for printing as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14758 a graph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14759
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14760 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14761 Fifth, write a function to print the results as a graph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14762 @end itemize
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14763
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14764 This is quite a project! But if we take each step slowly, it will not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14765 be difficult.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14766
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14767 @node Words and Symbols, Syntax, Divide and Conquer, Words in a defun
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14768 @section What to Count?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14769 @cindex Words and symbols in defun
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14770
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14771 When we first start thinking about how to count the words in a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14772 function definition, the first question is (or ought to be) what are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14773 we going to count? When we speak of `words' with respect to a Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14774 function definition, we are actually speaking, in large part, of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14775 `symbols'. For example, the following @code{multiply-by-seven}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14776 function contains the five symbols @code{defun},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14777 @code{multiply-by-seven}, @code{number}, @code{*}, and @code{7}. In
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14778 addition, in the documentation string, it contains the four words
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14779 @samp{Multiply}, @samp{NUMBER}, @samp{by}, and @samp{seven}. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14780 symbol @samp{number} is repeated, so the definition contains a total
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14781 of ten words and symbols.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14782
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14783 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14784 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14785 (defun multiply-by-seven (number)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14786 "Multiply NUMBER by seven."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14787 (* 7 number))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14788 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14789 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14790
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14791 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14792 However, if we mark the @code{multiply-by-seven} definition with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14793 @kbd{C-M-h} (@code{mark-defun}), and then call
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14794 @code{count-words-region} on it, we will find that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14795 @code{count-words-region} claims the definition has eleven words, not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14796 ten! Something is wrong!
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14797
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14798 The problem is twofold: @code{count-words-region} does not count the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14799 @samp{*} as a word, and it counts the single symbol,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14800 @code{multiply-by-seven}, as containing three words. The hyphens are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14801 treated as if they were interword spaces rather than intraword
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14802 connectors: @samp{multiply-by-seven} is counted as if it were written
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14803 @samp{multiply by seven}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14804
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14805 The cause of this confusion is the regular expression search within
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14806 the @code{count-words-region} definition that moves point forward word
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14807 by word. In the canonical version of @code{count-words-region}, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14808 regexp is:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14809
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14810 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14811 "\\w+\\W*"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14812 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14813
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14814 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14815 This regular expression is a pattern defining one or more word
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14816 constituent characters possibly followed by one or more characters
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14817 that are not word constituents. What is meant by `word constituent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14818 characters' brings us to the issue of syntax, which is worth a section
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14819 of its own.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14820
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14821 @node Syntax, count-words-in-defun, Words and Symbols, Words in a defun
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14822 @section What Constitutes a Word or Symbol?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14823 @cindex Syntax categories and tables
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14824
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14825 Emacs treats different characters as belonging to different
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14826 @dfn{syntax categories}. For example, the regular expression,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14827 @samp{\\w+}, is a pattern specifying one or more @emph{word
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14828 constituent} characters. Word constituent characters are members of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14829 one syntax category. Other syntax categories include the class of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14830 punctuation characters, such as the period and the comma, and the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14831 class of whitespace characters, such as the blank space and the tab
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14832 character. (For more information, see @ref{Syntax, Syntax, The Syntax
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14833 Table, emacs, The GNU Emacs Manual}, and @ref{Syntax Tables, , Syntax
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14834 Tables, elisp, The GNU Emacs Lisp Reference Manual}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14835
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14836 Syntax tables specify which characters belong to which categories.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14837 Usually, a hyphen is not specified as a `word constituent character'.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14838 Instead, it is specified as being in the `class of characters that are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14839 part of symbol names but not words.' This means that the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14840 @code{count-words-region} function treats it in the same way it treats
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14841 an interword white space, which is why @code{count-words-region}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14842 counts @samp{multiply-by-seven} as three words.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14843
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14844 There are two ways to cause Emacs to count @samp{multiply-by-seven} as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14845 one symbol: modify the syntax table or modify the regular expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14846
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14847 We could redefine a hyphen as a word constituent character by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14848 modifying the syntax table that Emacs keeps for each mode. This
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14849 action would serve our purpose, except that a hyphen is merely the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14850 most common character within symbols that is not typically a word
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14851 constituent character; there are others, too.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14852
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14853 Alternatively, we can redefine the regular expression used in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14854 @code{count-words} definition so as to include symbols. This
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14855 procedure has the merit of clarity, but the task is a little tricky.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14856
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14857 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14858 The first part is simple enough: the pattern must match ``at least one
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14859 character that is a word or symbol constituent''. Thus:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14860
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14861 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14862 "\\(\\w\\|\\s_\\)+"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14863 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14864
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14865 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14866 The @samp{\\(} is the first part of the grouping construct that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14867 includes the @samp{\\w} and the @samp{\\s_} as alternatives, separated
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14868 by the @samp{\\|}. The @samp{\\w} matches any word-constituent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14869 character and the @samp{\\s_} matches any character that is part of a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14870 symbol name but not a word-constituent character. The @samp{+}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14871 following the group indicates that the word or symbol constituent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14872 characters must be matched at least once.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14873
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14874 However, the second part of the regexp is more difficult to design.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14875 What we want is to follow the first part with ``optionally one or more
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14876 characters that are not constituents of a word or symbol''. At first,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14877 I thought I could define this with the following:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14878
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14879 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14880 "\\(\\W\\|\\S_\\)*"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14881 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14882
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14883 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14884 The upper case @samp{W} and @samp{S} match characters that are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14885 @emph{not} word or symbol constituents. Unfortunately, this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14886 expression matches any character that is either not a word constituent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14887 or not a symbol constituent. This matches any character!
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14888
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14889 I then noticed that every word or symbol in my test region was
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14890 followed by white space (blank space, tab, or newline). So I tried
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14891 placing a pattern to match one or more blank spaces after the pattern
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14892 for one or more word or symbol constituents. This failed, too. Words
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14893 and symbols are often separated by whitespace, but in actual code
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14894 parentheses may follow symbols and punctuation may follow words. So
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14895 finally, I designed a pattern in which the word or symbol constituents
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14896 are followed optionally by characters that are not white space and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14897 then followed optionally by white space.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14898
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14899 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14900 Here is the full regular expression:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14901
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14902 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14903 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14904 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14905
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14906 @node count-words-in-defun, Several defuns, Syntax, Words in a defun
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14907 @section The @code{count-words-in-defun} Function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14908 @cindex Counting words in a @code{defun}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14909
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14910 We have seen that there are several ways to write a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14911 @code{count-word-region} function. To write a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14912 @code{count-words-in-defun}, we need merely adapt one of these
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14913 versions.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14914
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14915 The version that uses a @code{while} loop is easy to understand, so I
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14916 am going to adapt that. Because @code{count-words-in-defun} will be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14917 part of a more complex program, it need not be interactive and it need
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14918 not display a message but just return the count. These considerations
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14919 simplify the definition a little.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14920
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14921 On the other hand, @code{count-words-in-defun} will be used within a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14922 buffer that contains function definitions. Consequently, it is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14923 reasonable to ask that the function determine whether it is called
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14924 when point is within a function definition, and if it is, to return
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14925 the count for that definition. This adds complexity to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14926 definition, but saves us from needing to pass arguments to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14927 function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14928
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14929 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14930 These considerations lead us to prepare the following template:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14931
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14932 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14933 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14934 (defun count-words-in-defun ()
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14935 "@var{documentation}@dots{}"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14936 (@var{set up}@dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14937 (@var{while loop}@dots{})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14938 @var{return count})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14939 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14940 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14941
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14942 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14943 As usual, our job is to fill in the slots.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14944
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14945 First, the set up.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14946
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14947 We are presuming that this function will be called within a buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14948 containing function definitions. Point will either be within a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14949 function definition or not. For @code{count-words-in-defun} to work,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14950 point must move to the beginning of the definition, a counter must
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14951 start at zero, and the counting loop must stop when point reaches the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14952 end of the definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14953
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14954 The @code{beginning-of-defun} function searches backwards for an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14955 opening delimiter such as a @samp{(} at the beginning of a line, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14956 moves point to that position, or else to the limit of the search. In
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14957 practice, this means that @code{beginning-of-defun} moves point to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14958 beginning of an enclosing or preceding function definition, or else to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14959 the beginning of the buffer. We can use @code{beginning-of-defun} to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14960 place point where we wish to start.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14961
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14962 The @code{while} loop requires a counter to keep track of the words or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14963 symbols being counted. A @code{let} expression can be used to create
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14964 a local variable for this purpose, and bind it to an initial value of zero.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14965
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14966 The @code{end-of-defun} function works like @code{beginning-of-defun}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14967 except that it moves point to the end of the definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14968 @code{end-of-defun} can be used as part of an expression that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14969 determines the position of the end of the definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14970
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14971 The set up for @code{count-words-in-defun} takes shape rapidly: first
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14972 we move point to the beginning of the definition, then we create a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14973 local variable to hold the count, and finally, we record the position
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14974 of the end of the definition so the @code{while} loop will know when to stop
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14975 looping.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14976
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14977 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14978 The code looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14979
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14980 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14981 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14982 (beginning-of-defun)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14983 (let ((count 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14984 (end (save-excursion (end-of-defun) (point))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14985 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14986 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14987
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14988 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14989 The code is simple. The only slight complication is likely to concern
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14990 @code{end}: it is bound to the position of the end of the definition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14991 by a @code{save-excursion} expression that returns the value of point
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14992 after @code{end-of-defun} temporarily moves it to the end of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14993 definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14994
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14995 The second part of the @code{count-words-in-defun}, after the set up,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14996 is the @code{while} loop.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14997
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14998 The loop must contain an expression that jumps point forward word by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14999 word and symbol by symbol, and another expression that counts the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15000 jumps. The true-or-false-test for the @code{while} loop should test
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15001 true so long as point should jump forward, and false when point is at
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15002 the end of the definition. We have already redefined the regular
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15003 expression for this (@pxref{Syntax}), so the loop is straightforward:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15004
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15005 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15006 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15007 (while (and (< (point) end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15008 (re-search-forward
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15009 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" end t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15010 (setq count (1+ count)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15011 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15012 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15013
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15014 The third part of the function definition returns the count of words
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15015 and symbols. This part is the last expression within the body of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15016 @code{let} expression, and can be, very simply, the local variable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15017 @code{count}, which when evaluated returns the count.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15018
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15019 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15020 Put together, the @code{count-words-in-defun} definition looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15021
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15022 @findex count-words-in-defun
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15023 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15024 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15025 (defun count-words-in-defun ()
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15026 "Return the number of words and symbols in a defun."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15027 (beginning-of-defun)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15028 (let ((count 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15029 (end (save-excursion (end-of-defun) (point))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15030 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15031 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15032 (while
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15033 (and (< (point) end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15034 (re-search-forward
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15035 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15036 end t))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15037 (setq count (1+ count)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15038 count))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15039 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15040 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15041
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15042 How to test this? The function is not interactive, but it is easy to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15043 put a wrapper around the function to make it interactive; we can use
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15044 almost the same code as for the recursive version of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15045 @code{count-words-region}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15046
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15047 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15048 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15049 ;;; @r{Interactive version.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15050 (defun count-words-defun ()
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15051 "Number of words and symbols in a function definition."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15052 (interactive)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15053 (message
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15054 "Counting words and symbols in function definition ... ")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15055 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15056 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15057 (let ((count (count-words-in-defun)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15058 (cond
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15059 ((zerop count)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15060 (message
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15061 "The definition does NOT have any words or symbols."))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15062 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15063 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15064 ((= 1 count)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15065 (message
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15066 "The definition has 1 word or symbol."))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15067 (t
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15068 (message
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15069 "The definition has %d words or symbols." count)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15070 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15071 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15072
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15073 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15074 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15075 Let's re-use @kbd{C-c =} as a convenient keybinding:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15076
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15077 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15078 (global-set-key "\C-c=" 'count-words-defun)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15079 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15080
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15081 Now we can try out @code{count-words-defun}: install both
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15082 @code{count-words-in-defun} and @code{count-words-defun}, and set the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15083 keybinding, and then place the cursor within the following definition:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15084
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15085 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15086 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15087 (defun multiply-by-seven (number)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15088 "Multiply NUMBER by seven."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15089 (* 7 number))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15090 @result{} 10
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15091 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15092 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15093
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15094 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15095 Success! The definition has 10 words and symbols.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15096
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15097 The next problem is to count the numbers of words and symbols in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15098 several definitions within a single file.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15099
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15100 @node Several defuns, Find a File, count-words-in-defun, Words in a defun
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15101 @section Count Several @code{defuns} Within a File
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15102
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15103 A file such as @file{simple.el} may have a hundred or more function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15104 definitions within it. Our long term goal is to collect statistics on
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15105 many files, but as a first step, our immediate goal is to collect
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15106 statistics on one file.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15107
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15108 The information will be a series of numbers, each number being the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15109 length of a function definition. We can store the numbers in a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15110
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15111 We know that we will want to incorporate the information regarding one
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15112 file with information about many other files; this means that the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15113 function for counting definition lengths within one file need only
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15114 return the list of lengths. It need not and should not display any
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15115 messages.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15116
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15117 The word count commands contain one expression to jump point forward
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15118 word by word and another expression to count the jumps. The function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15119 to return the lengths of definitions can be designed to work the same
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15120 way, with one expression to jump point forward definition by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15121 definition and another expression to construct the lengths' list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15122
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15123 This statement of the problem makes it elementary to write the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15124 function definition. Clearly, we will start the count at the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15125 beginning of the file, so the first command will be @code{(goto-char
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15126 (point-min))}. Next, we start the @code{while} loop; and the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15127 true-or-false test of the loop can be a regular expression search for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15128 the next function definition---so long as the search succeeds, point
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15129 is moved forward and then the body of the loop is evaluated. The body
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15130 needs an expression that constructs the lengths' list. @code{cons},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15131 the list construction command, can be used to create the list. That
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15132 is almost all there is to it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15133
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15134 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15135 Here is what this fragment of code looks like:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15136
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15137 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15138 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15139 (goto-char (point-min))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15140 (while (re-search-forward "^(defun" nil t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15141 (setq lengths-list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15142 (cons (count-words-in-defun) lengths-list)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15143 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15144 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15145
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15146 What we have left out is the mechanism for finding the file that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15147 contains the function definitions.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15148
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15149 In previous examples, we either used this, the Info file, or we
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15150 switched back and forth to some other buffer, such as the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15151 @file{*scratch*} buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15152
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15153 Finding a file is a new process that we have not yet discussed.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15154
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15155 @node Find a File, lengths-list-file, Several defuns, Words in a defun
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15156 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15157 @section Find a File
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15158 @cindex Find a File
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15159
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15160 To find a file in Emacs, you use the @kbd{C-x C-f} (@code{find-file})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15161 command. This command is almost, but not quite right for the lengths
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15162 problem.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15163
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15164 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15165 Let's look at the source for @code{find-file}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15166
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15167 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15168 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15169 (defun find-file (filename)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15170 "Edit file FILENAME.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15171 Switch to a buffer visiting file FILENAME,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15172 creating one if none already exists."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15173 (interactive "FFind file: ")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15174 (switch-to-buffer (find-file-noselect filename)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15175 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15176 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15177
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15178 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15179 (The most recent version of the @code{find-file} function definition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15180 permits you to specify optional wildcards to visit multiple files; that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15181 makes the definition more complex and we will not discuss it here,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15182 since it is not relevant. You can see its source using either
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15183 @kbd{M-.} (@code{find-tag}) or @kbd{C-h f} (@code{describe-function}).)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15184
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15185 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15186 In Emacs 22
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15187 (defun find-file (filename &optional wildcards)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15188 "Edit file FILENAME.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15189 Switch to a buffer visiting file FILENAME,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15190 creating one if none already exists.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15191 Interactively, the default if you just type RET is the current directory,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15192 but the visited file name is available through the minibuffer history:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15193 type M-n to pull it into the minibuffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15194
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15195 Interactively, or if WILDCARDS is non-nil in a call from Lisp,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15196 expand wildcards (if any) and visit multiple files. You can
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15197 suppress wildcard expansion by setting `find-file-wildcards' to nil.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15198
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15199 To visit a file without any kind of conversion and without
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15200 automatically choosing a major mode, use \\[find-file-literally]."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15201 (interactive (find-file-read-args "Find file: " nil))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15202 (let ((value (find-file-noselect filename nil nil wildcards)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15203 (if (listp value)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15204 (mapcar 'switch-to-buffer (nreverse value))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15205 (switch-to-buffer value))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15206 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15207
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15208 The definition I am showing possesses short but complete documentation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15209 and an interactive specification that prompts you for a file name when
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15210 you use the command interactively. The body of the definition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15211 contains two functions, @code{find-file-noselect} and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15212 @code{switch-to-buffer}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15213
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15214 According to its documentation as shown by @kbd{C-h f} (the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15215 @code{describe-function} command), the @code{find-file-noselect}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15216 function reads the named file into a buffer and returns the buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15217 (Its most recent version includes an optional wildcards argument,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15218 too, as well as another to read a file literally and an other you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15219 suppress warning messages. These optional arguments are irrelevant.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15220
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15221 However, the @code{find-file-noselect} function does not select the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15222 buffer in which it puts the file. Emacs does not switch its attention
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15223 (or yours if you are using @code{find-file-noselect}) to the selected
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15224 buffer. That is what @code{switch-to-buffer} does: it switches the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15225 buffer to which Emacs attention is directed; and it switches the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15226 buffer displayed in the window to the new buffer. We have discussed
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15227 buffer switching elsewhere. (@xref{Switching Buffers}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15228
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15229 In this histogram project, we do not need to display each file on the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15230 screen as the program determines the length of each definition within
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15231 it. Instead of employing @code{switch-to-buffer}, we can work with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15232 @code{set-buffer}, which redirects the attention of the computer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15233 program to a different buffer but does not redisplay it on the screen.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15234 So instead of calling on @code{find-file} to do the job, we must write
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15235 our own expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15236
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15237 The task is easy: use @code{find-file-noselect} and @code{set-buffer}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15238
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15239 @node lengths-list-file, Several files, Find a File, Words in a defun
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15240 @section @code{lengths-list-file} in Detail
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15241
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15242 The core of the @code{lengths-list-file} function is a @code{while}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15243 loop containing a function to move point forward `defun by defun' and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15244 a function to count the number of words and symbols in each defun.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15245 This core must be surrounded by functions that do various other tasks,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15246 including finding the file, and ensuring that point starts out at the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15247 beginning of the file. The function definition looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15248 @findex lengths-list-file
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15249
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15250 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15251 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15252 (defun lengths-list-file (filename)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15253 "Return list of definitions' lengths within FILE.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15254 The returned list is a list of numbers.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15255 Each number is the number of words or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15256 symbols in one function definition."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15257 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15258 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15259 (message "Working on `%s' ... " filename)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15260 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15261 (let ((buffer (find-file-noselect filename))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15262 (lengths-list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15263 (set-buffer buffer)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15264 (setq buffer-read-only t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15265 (widen)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15266 (goto-char (point-min))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15267 (while (re-search-forward "^(defun" nil t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15268 (setq lengths-list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15269 (cons (count-words-in-defun) lengths-list)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15270 (kill-buffer buffer)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15271 lengths-list)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15272 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15273 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15274
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15275 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15276 The function is passed one argument, the name of the file on which it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15277 will work. It has four lines of documentation, but no interactive
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15278 specification. Since people worry that a computer is broken if they
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15279 don't see anything going on, the first line of the body is a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15280 message.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15281
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15282 The next line contains a @code{save-excursion} that returns Emacs'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15283 attention to the current buffer when the function completes. This is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15284 useful in case you embed this function in another function that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15285 presumes point is restored to the original buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15286
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15287 In the varlist of the @code{let} expression, Emacs finds the file and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15288 binds the local variable @code{buffer} to the buffer containing the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15289 file. At the same time, Emacs creates @code{lengths-list} as a local
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15290 variable.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15291
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15292 Next, Emacs switches its attention to the buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15293
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15294 In the following line, Emacs makes the buffer read-only. Ideally,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15295 this line is not necessary. None of the functions for counting words
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15296 and symbols in a function definition should change the buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15297 Besides, the buffer is not going to be saved, even if it were changed.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15298 This line is entirely the consequence of great, perhaps excessive,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15299 caution. The reason for the caution is that this function and those
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15300 it calls work on the sources for Emacs and it is inconvenient if they
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15301 are inadvertently modified. It goes without saying that I did not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15302 realize a need for this line until an experiment went awry and started
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15303 to modify my Emacs source files @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15304
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15305 Next comes a call to widen the buffer if it is narrowed. This
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15306 function is usually not needed---Emacs creates a fresh buffer if none
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15307 already exists; but if a buffer visiting the file already exists Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15308 returns that one. In this case, the buffer may be narrowed and must
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15309 be widened. If we wanted to be fully `user-friendly', we would
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15310 arrange to save the restriction and the location of point, but we
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15311 won't.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15312
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15313 The @code{(goto-char (point-min))} expression moves point to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15314 beginning of the buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15315
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15316 Then comes a @code{while} loop in which the `work' of the function is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15317 carried out. In the loop, Emacs determines the length of each
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15318 definition and constructs a lengths' list containing the information.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15319
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15320 Emacs kills the buffer after working through it. This is to save
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15321 space inside of Emacs. My version of GNU Emacs 19 contained over 300
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15322 source files of interest; GNU Emacs 22 contains over a thousand source
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15323 files. Another function will apply @code{lengths-list-file} to each
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15324 of the files.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15325
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15326 Finally, the last expression within the @code{let} expression is the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15327 @code{lengths-list} variable; its value is returned as the value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15328 the whole function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15329
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15330 You can try this function by installing it in the usual fashion. Then
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15331 place your cursor after the following expression and type @kbd{C-x
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15332 C-e} (@code{eval-last-sexp}).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15333
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15334 @c !!! 22.1.1 lisp sources location here
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15335 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15336 (lengths-list-file
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15337 "/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/debug.el")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15338 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15339
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15340 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15341 (You may need to change the pathname of the file; the one here is for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15342 GNU Emacs version 22.1.1. To change the expression, copy it to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15343 the @file{*scratch*} buffer and edit it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15344
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15345 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15346 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15347 (Also, to see the full length of the list, rather than a truncated
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15348 version, you may have to evaluate the following:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15349
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15350 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15351 (custom-set-variables '(eval-expression-print-length nil))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15352 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15353
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15354 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15355 (@xref{defcustom, , Specifying Variables using @code{defcustom}}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15356 Then evaluate the @code{lengths-list-file} expression.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15357
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15358 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15359 The lengths' list for @file{debug.el} takes less than a second to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15360 produce and looks like this in GNU Emacs 22:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15361
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15362 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15363 (83 113 105 144 289 22 30 97 48 89 25 52 52 88 28 29 77 49 43 290 232 587)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15364 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15365
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15366 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15367 (Using my old machine, the version 19 lengths' list for @file{debug.el}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15368 took seven seconds to produce and looked like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15369
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15370 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15371 (75 41 80 62 20 45 44 68 45 12 34 235)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15372 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15373
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15374 (The newer version of @file{debug.el} contains more defuns than the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15375 earlier one; and my new machine is much faster than the old one.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15376
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15377 Note that the length of the last definition in the file is first in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15378 the list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15379
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15380 @node Several files, Several files recursively, lengths-list-file, Words in a defun
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15381 @section Count Words in @code{defuns} in Different Files
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15382
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15383 In the previous section, we created a function that returns a list of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15384 the lengths of each definition in a file. Now, we want to define a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15385 function to return a master list of the lengths of the definitions in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15386 a list of files.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15387
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15388 Working on each of a list of files is a repetitious act, so we can use
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15389 either a @code{while} loop or recursion.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15390
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15391 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15392 * lengths-list-many-files:: Return a list of the lengths of defuns.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15393 * append:: Attach one list to another.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15394 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15395
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15396 @node lengths-list-many-files, append, Several files, Several files
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15397 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15398 @unnumberedsubsec Determine the lengths of @code{defuns}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15399 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15400
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15401 The design using a @code{while} loop is routine. The argument passed
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15402 the function is a list of files. As we saw earlier (@pxref{Loop
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15403 Example}), you can write a @code{while} loop so that the body of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15404 loop is evaluated if such a list contains elements, but to exit the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15405 loop if the list is empty. For this design to work, the body of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15406 loop must contain an expression that shortens the list each time the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15407 body is evaluated, so that eventually the list is empty. The usual
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15408 technique is to set the value of the list to the value of the @sc{cdr}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15409 of the list each time the body is evaluated.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15410
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15411 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15412 The template looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15413
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15414 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15415 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15416 (while @var{test-whether-list-is-empty}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15417 @var{body}@dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15418 @var{set-list-to-cdr-of-list})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15419 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15420 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15421
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15422 Also, we remember that a @code{while} loop returns @code{nil} (the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15423 result of evaluating the true-or-false-test), not the result of any
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15424 evaluation within its body. (The evaluations within the body of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15425 loop are done for their side effects.) However, the expression that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15426 sets the lengths' list is part of the body---and that is the value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15427 that we want returned by the function as a whole. To do this, we
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15428 enclose the @code{while} loop within a @code{let} expression, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15429 arrange that the last element of the @code{let} expression contains
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15430 the value of the lengths' list. (@xref{Incrementing Example, , Loop
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15431 Example with an Incrementing Counter}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15432
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15433 @findex lengths-list-many-files
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15434 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15435 These considerations lead us directly to the function itself:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15436
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15437 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15438 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15439 ;;; @r{Use @code{while} loop.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15440 (defun lengths-list-many-files (list-of-files)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15441 "Return list of lengths of defuns in LIST-OF-FILES."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15442 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15443 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15444 (let (lengths-list)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15445
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15446 ;;; @r{true-or-false-test}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15447 (while list-of-files
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15448 (setq lengths-list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15449 (append
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15450 lengths-list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15451
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15452 ;;; @r{Generate a lengths' list.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15453 (lengths-list-file
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15454 (expand-file-name (car list-of-files)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15455 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15456
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15457 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15458 ;;; @r{Make files' list shorter.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15459 (setq list-of-files (cdr list-of-files)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15460
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15461 ;;; @r{Return final value of lengths' list.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15462 lengths-list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15463 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15464 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15465
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15466 @code{expand-file-name} is a built-in function that converts a file
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15467 name to the absolute, long, path name form. The function employs the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15468 name of the directory in which the function is called.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15469
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15470 @c !!! 22.1.1 lisp sources location here
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15471 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15472 Thus, if @code{expand-file-name} is called on @code{debug.el} when
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15473 Emacs is visiting the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15474 @file{/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/} directory,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15475
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15476 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15477 debug.el
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15478 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15479
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15480 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15481 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15482 becomes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15483
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15484 @c !!! 22.1.1 lisp sources location here
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15485 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15486 /usr/local/share/emacs/22.1.1/lisp/emacs-lisp/debug.el
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15487 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15488
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15489 The only other new element of this function definition is the as yet
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15490 unstudied function @code{append}, which merits a short section for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15491 itself.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15492
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15493 @node append, , lengths-list-many-files, Several files
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15494 @subsection The @code{append} Function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15495
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15496 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15497 The @code{append} function attaches one list to another. Thus,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15498
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15499 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15500 (append '(1 2 3 4) '(5 6 7 8))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15501 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15502
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15503 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15504 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15505 produces the list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15506
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15507 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15508 (1 2 3 4 5 6 7 8)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15509 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15510
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15511 This is exactly how we want to attach two lengths' lists produced by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15512 @code{lengths-list-file} to each other. The results contrast with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15513 @code{cons},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15514
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15515 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15516 (cons '(1 2 3 4) '(5 6 7 8))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15517 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15518
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15519 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15520 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15521 which constructs a new list in which the first argument to @code{cons}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15522 becomes the first element of the new list:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15523
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15524 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15525 ((1 2 3 4) 5 6 7 8)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15526 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15527
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15528 @node Several files recursively, Prepare the data, Several files, Words in a defun
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15529 @section Recursively Count Words in Different Files
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15530
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15531 Besides a @code{while} loop, you can work on each of a list of files
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15532 with recursion. A recursive version of @code{lengths-list-many-files}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15533 is short and simple.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15534
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15535 The recursive function has the usual parts: the `do-again-test', the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15536 `next-step-expression', and the recursive call. The `do-again-test'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15537 determines whether the function should call itself again, which it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15538 will do if the @code{list-of-files} contains any remaining elements;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15539 the `next-step-expression' resets the @code{list-of-files} to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15540 @sc{cdr} of itself, so eventually the list will be empty; and the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15541 recursive call calls itself on the shorter list. The complete
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15542 function is shorter than this description!
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15543 @findex recursive-lengths-list-many-files
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15544
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15545 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15546 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15547 (defun recursive-lengths-list-many-files (list-of-files)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15548 "Return list of lengths of each defun in LIST-OF-FILES."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15549 (if list-of-files ; @r{do-again-test}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15550 (append
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15551 (lengths-list-file
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15552 (expand-file-name (car list-of-files)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15553 (recursive-lengths-list-many-files
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15554 (cdr list-of-files)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15555 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15556 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15557
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15558 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15559 In a sentence, the function returns the lengths' list for the first of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15560 the @code{list-of-files} appended to the result of calling itself on
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15561 the rest of the @code{list-of-files}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15562
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15563 Here is a test of @code{recursive-lengths-list-many-files}, along with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15564 the results of running @code{lengths-list-file} on each of the files
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15565 individually.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15566
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15567 Install @code{recursive-lengths-list-many-files} and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15568 @code{lengths-list-file}, if necessary, and then evaluate the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15569 following expressions. You may need to change the files' pathnames;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15570 those here work when this Info file and the Emacs sources are located
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15571 in their customary places. To change the expressions, copy them to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15572 the @file{*scratch*} buffer, edit them, and then evaluate them.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15573
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15574 The results are shown after the @samp{@result{}}. (These results are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15575 for files from Emacs version 22.1.1; files from other versions of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15576 Emacs may produce different results.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15577
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15578 @c !!! 22.1.1 lisp sources location here
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15579 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15580 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15581 (cd "/usr/local/share/emacs/22.1.1/")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15582
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15583 (lengths-list-file "./lisp/macros.el")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15584 @result{} (283 263 480 90)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15585 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15586
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15587 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15588 (lengths-list-file "./lisp/mail/mailalias.el")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15589 @result{} (38 32 29 95 178 180 321 218 324)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15590 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15591
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15592 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15593 (lengths-list-file "./lisp/makesum.el")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15594 @result{} (85 181)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15595 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15596
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15597 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15598 (recursive-lengths-list-many-files
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15599 '("./lisp/macros.el"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15600 "./lisp/mail/mailalias.el"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15601 "./lisp/makesum.el"))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15602 @result{} (283 263 480 90 38 32 29 95 178 180 321 218 324 85 181)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15603 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15604 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15605
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15606 The @code{recursive-lengths-list-many-files} function produces the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15607 output we want.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15608
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15609 The next step is to prepare the data in the list for display in a graph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15610
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15611 @node Prepare the data, , Several files recursively, Words in a defun
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15612 @section Prepare the Data for Display in a Graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15613
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15614 The @code{recursive-lengths-list-many-files} function returns a list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15615 of numbers. Each number records the length of a function definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15616 What we need to do now is transform this data into a list of numbers
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15617 suitable for generating a graph. The new list will tell how many
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15618 functions definitions contain less than 10 words and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15619 symbols, how many contain between 10 and 19 words and symbols, how
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15620 many contain between 20 and 29 words and symbols, and so on.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15621
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15622 In brief, we need to go through the lengths' list produced by the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15623 @code{recursive-lengths-list-many-files} function and count the number
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15624 of defuns within each range of lengths, and produce a list of those
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15625 numbers.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15626
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15627 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15628 * Data for Display in Detail::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15629 * Sorting:: Sorting lists.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15630 * Files List:: Making a list of files.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15631 * Counting function definitions::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15632 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15633
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15634 @node Data for Display in Detail, Sorting, Prepare the data, Prepare the data
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15635 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15636 @unnumberedsubsec The Data for Display in Detail
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15637 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15638
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15639 Based on what we have done before, we can readily foresee that it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15640 should not be too hard to write a function that `@sc{cdr}s' down the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15641 lengths' list, looks at each element, determines which length range it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15642 is in, and increments a counter for that range.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15643
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15644 However, before beginning to write such a function, we should consider
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15645 the advantages of sorting the lengths' list first, so the numbers are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15646 ordered from smallest to largest. First, sorting will make it easier
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15647 to count the numbers in each range, since two adjacent numbers will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15648 either be in the same length range or in adjacent ranges. Second, by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15649 inspecting a sorted list, we can discover the highest and lowest
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15650 number, and thereby determine the largest and smallest length range
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15651 that we will need.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15652
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15653 @node Sorting, Files List, Data for Display in Detail, Prepare the data
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15654 @subsection Sorting Lists
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15655 @findex sort
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15656
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15657 Emacs contains a function to sort lists, called (as you might guess)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15658 @code{sort}. The @code{sort} function takes two arguments, the list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15659 to be sorted, and a predicate that determines whether the first of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15660 two list elements is ``less'' than the second.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15661
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15662 As we saw earlier (@pxref{Wrong Type of Argument, , Using the Wrong
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15663 Type Object as an Argument}), a predicate is a function that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15664 determines whether some property is true or false. The @code{sort}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15665 function will reorder a list according to whatever property the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15666 predicate uses; this means that @code{sort} can be used to sort
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15667 non-numeric lists by non-numeric criteria---it can, for example,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15668 alphabetize a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15669
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15670 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15671 The @code{<} function is used when sorting a numeric list. For example,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15672
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15673 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15674 (sort '(4 8 21 17 33 7 21 7) '<)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15675 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15676
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15677 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15678 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15679 produces this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15680
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15681 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15682 (4 7 7 8 17 21 21 33)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15683 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15684
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15685 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15686 (Note that in this example, both the arguments are quoted so that the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15687 symbols are not evaluated before being passed to @code{sort} as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15688 arguments.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15689
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15690 Sorting the list returned by the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15691 @code{recursive-lengths-list-many-files} function is straightforward;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15692 it uses the @code{<} function:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15693
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15694 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15695 2006 Oct 29
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15696 In GNU Emacs 22, eval
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15697 (progn
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15698 (cd "/usr/local/share/emacs/22.0.50/")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15699 (sort
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15700 (recursive-lengths-list-many-files
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15701 '("./lisp/macros.el"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15702 "./lisp/mail/mailalias.el"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15703 "./lisp/makesum.el"))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15704 '<))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15705
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15706 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15707
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15708 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15709 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15710 (sort
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15711 (recursive-lengths-list-many-files
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15712 '("./lisp/macros.el"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15713 "./lisp/mailalias.el"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15714 "./lisp/makesum.el"))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15715 '<)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15716 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15717 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15718
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15719 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15720 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15721 which produces:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15722
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15723 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15724 (29 32 38 85 90 95 178 180 181 218 263 283 321 324 480)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15725 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15726
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15727 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15728 (Note that in this example, the first argument to @code{sort} is not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15729 quoted, since the expression must be evaluated so as to produce the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15730 list that is passed to @code{sort}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15731
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15732 @node Files List, Counting function definitions, Sorting, Prepare the data
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15733 @subsection Making a List of Files
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15734
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15735 The @code{recursive-lengths-list-many-files} function requires a list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15736 of files as its argument. For our test examples, we constructed such
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15737 a list by hand; but the Emacs Lisp source directory is too large for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15738 us to do for that. Instead, we will write a function to do the job
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15739 for us. In this function, we will use both a @code{while} loop and a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15740 recursive call.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15741
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15742 @findex directory-files
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15743 We did not have to write a function like this for older versions of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15744 GNU Emacs, since they placed all the @samp{.el} files in one
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15745 directory. Instead, we were able to use the @code{directory-files}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15746 function, which lists the names of files that match a specified
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15747 pattern within a single directory.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15748
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15749 However, recent versions of Emacs place Emacs Lisp files in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15750 sub-directories of the top level @file{lisp} directory. This
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15751 re-arrangement eases navigation. For example, all the mail related
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15752 files are in a @file{lisp} sub-directory called @file{mail}. But at
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15753 the same time, this arrangement forces us to create a file listing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15754 function that descends into the sub-directories.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15755
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15756 @findex files-in-below-directory
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15757 We can create this function, called @code{files-in-below-directory},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15758 using familiar functions such as @code{car}, @code{nthcdr}, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15759 @code{substring} in conjunction with an existing function called
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15760 @code{directory-files-and-attributes}. This latter function not only
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15761 lists all the filenames in a directory, including the names
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15762 of sub-directories, but also their attributes.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15763
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15764 To restate our goal: to create a function that will enable us
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15765 to feed filenames to @code{recursive-lengths-list-many-files}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15766 as a list that looks like this (but with more elements):
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15767
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15768 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15769 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15770 ("./lisp/macros.el"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15771 "./lisp/mail/rmail.el"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15772 "./lisp/makesum.el")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15773 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15774 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15775
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15776 The @code{directory-files-and-attributes} function returns a list of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15777 lists. Each of the lists within the main list consists of 13
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15778 elements. The first element is a string that contains the name of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15779 file -- which, in GNU/Linux, may be a `directory file', that is to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15780 say, a file with the special attributes of a directory. The second
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15781 element of the list is @code{t} for a directory, a string
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15782 for symbolic link (the string is the name linked to), or @code{nil}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15783
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15784 For example, the first @samp{.el} file in the @file{lisp/} directory
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15785 is @file{abbrev.el}. Its name is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15786 @file{/usr/local/share/emacs/22.1.1/lisp/abbrev.el} and it is not a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15787 directory or a symbolic link.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15788
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15789 @need 1000
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15790 This is how @code{directory-files-and-attributes} lists that file and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15791 its attributes:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15792
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15793 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15794 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15795 ("abbrev.el"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15796 nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15797 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15798 1000
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15799 100
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15800 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15801 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15802 (17733 259)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15803 (17491 28834)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15804 (17596 62124)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15805 13157
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15806 "-rw-rw-r--"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15807 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15808 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15809 nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15810 2971624
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15811 773)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15812 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15813 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15814
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15815 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15816 On the other hand, @file{mail/} is a directory within the @file{lisp/}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15817 directory. The beginning of its listing looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15818
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15819 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15820 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15821 ("mail"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15822 t
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15823 @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15824 )
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15825 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15826 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15827
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15828 (To learn about the different attributes, look at the documentation of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15829 @code{file-attributes}. Bear in mind that the @code{file-attributes}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15830 function does not list the filename, so its first element is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15831 @code{directory-files-and-attributes}'s second element.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15832
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15833 We will want our new function, @code{files-in-below-directory}, to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15834 list the @samp{.el} files in the directory it is told to check, and in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15835 any directories below that directory.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15836
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15837 This gives us a hint on how to construct
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15838 @code{files-in-below-directory}: within a directory, the function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15839 should add @samp{.el} filenames to a list; and if, within a directory,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15840 the function comes upon a sub-directory, it should go into that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15841 sub-directory and repeat its actions.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15842
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15843 However, we should note that every directory contains a name that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15844 refers to itself, called @file{.}, (``dot'') and a name that refers to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15845 its parent directory, called @file{..} (``double dot''). (In
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15846 @file{/}, the root directory, @file{..} refers to itself, since
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15847 @file{/} has no parent.) Clearly, we do not want our
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15848 @code{files-in-below-directory} function to enter those directories,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15849 since they always lead us, directly or indirectly, to the current
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15850 directory.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15851
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15852 Consequently, our @code{files-in-below-directory} function must do
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15853 several tasks:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15854
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15855 @itemize @bullet
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15856 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15857 Check to see whether it is looking at a filename that ends in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15858 @samp{.el}; and if so, add its name to a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15859
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15860 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15861 Check to see whether it is looking at a filename that is the name of a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15862 directory; and if so,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15863
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15864 @itemize @minus
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15865 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15866 Check to see whether it is looking at @file{.} or @file{..}; and if
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15867 so skip it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15868
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15869 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15870 Or else, go into that directory and repeat the process.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15871 @end itemize
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15872 @end itemize
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15873
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15874 Let's write a function definition to do these tasks. We will use a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15875 @code{while} loop to move from one filename to another within a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15876 directory, checking what needs to be done; and we will use a recursive
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15877 call to repeat the actions on each sub-directory. The recursive
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15878 pattern is `accumulate'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15879 (@pxref{Accumulate, , Recursive Pattern: @emph{accumulate}}),
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15880 using @code{append} as the combiner.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15881
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15882 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15883 (directory-files "/usr/local/src/emacs/lisp/" t "\\.el$")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15884 (shell-command "find /usr/local/src/emacs/lisp/ -name '*.el'")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15885
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15886 (directory-files "/usr/local/share/emacs/22.1.1/lisp/" t "\\.el$")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15887 (shell-command "find /usr/local/share/emacs/22.1.1/lisp/ -name '*.el'")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15888 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15889
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15890 @c /usr/local/share/emacs/22.1.1/lisp/
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15891
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15892 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15893 Here is the function:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15894
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15895 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15896 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15897 (defun files-in-below-directory (directory)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15898 "List the .el files in DIRECTORY and in its sub-directories."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15899 ;; Although the function will be used non-interactively,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15900 ;; it will be easier to test if we make it interactive.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15901 ;; The directory will have a name such as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15902 ;; "/usr/local/share/emacs/22.1.1/lisp/"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15903 (interactive "DDirectory name: ")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15904 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15905 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15906 (let (el-files-list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15907 (current-directory-list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15908 (directory-files-and-attributes directory t)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15909 ;; while we are in the current directory
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15910 (while current-directory-list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15911 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15912 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15913 (cond
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15914 ;; check to see whether filename ends in `.el'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15915 ;; and if so, append its name to a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15916 ((equal ".el" (substring (car (car current-directory-list)) -3))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15917 (setq el-files-list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15918 (cons (car (car current-directory-list)) el-files-list)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15919 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15920 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15921 ;; check whether filename is that of a directory
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15922 ((eq t (car (cdr (car current-directory-list))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15923 ;; decide whether to skip or recurse
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15924 (if
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15925 (equal "."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15926 (substring (car (car current-directory-list)) -1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15927 ;; then do nothing since filename is that of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15928 ;; current directory or parent, "." or ".."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15929 ()
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15930 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15931 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15932 ;; else descend into the directory and repeat the process
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15933 (setq el-files-list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15934 (append
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15935 (files-in-below-directory
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15936 (car (car current-directory-list)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15937 el-files-list)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15938 ;; move to the next filename in the list; this also
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15939 ;; shortens the list so the while loop eventually comes to an end
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15940 (setq current-directory-list (cdr current-directory-list)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15941 ;; return the filenames
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15942 el-files-list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15943 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15944 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15945
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15946 @c (files-in-below-directory "/usr/local/src/emacs/lisp/")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15947 @c (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15948
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15949 The @code{files-in-below-directory} @code{directory-files} function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15950 takes one argument, the name of a directory.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15951
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15952 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15953 Thus, on my system,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15954
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15955 @c (length (files-in-below-directory "/usr/local/src/emacs/lisp/"))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15956
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15957 @c !!! 22.1.1 lisp sources location here
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15958 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15959 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15960 (length
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15961 (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/"))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15962 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15963 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15964
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15965 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15966 tells me that in and below my Lisp sources directory are 1031
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15967 @samp{.el} files.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15968
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15969 @code{files-in-below-directory} returns a list in reverse alphabetical
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15970 order. An expression to sort the list in alphabetical order looks
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15971 like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15972
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15973 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15974 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15975 (sort
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15976 (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15977 'string-lessp)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15978 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15979 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15980
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15981 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15982 (defun test ()
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15983 "Test how long it takes to find lengths of all sorted elisp defuns."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15984 (insert "\n" (current-time-string) "\n")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15985 (sit-for 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15986 (sort
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15987 (recursive-lengths-list-many-files
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15988 (files-in-below-directory "/usr/local/src/emacs/lisp/"))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15989 '<)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15990 (insert (format "%s" (current-time-string))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15991 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15992
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15993 @node Counting function definitions, , Files List, Prepare the data
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15994 @subsection Counting function definitions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15995
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15996 Our immediate goal is to generate a list that tells us how many
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15997 function definitions contain fewer than 10 words and symbols, how many
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15998 contain between 10 and 19 words and symbols, how many contain between
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15999 20 and 29 words and symbols, and so on.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16000
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16001 With a sorted list of numbers, this is easy: count how many elements
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16002 of the list are smaller than 10, then, after moving past the numbers
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16003 just counted, count how many are smaller than 20, then, after moving
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16004 past the numbers just counted, count how many are smaller than 30, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16005 so on. Each of the numbers, 10, 20, 30, 40, and the like, is one
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16006 larger than the top of that range. We can call the list of such
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16007 numbers the @code{top-of-ranges} list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16008
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16009 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16010 If we wished, we could generate this list automatically, but it is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16011 simpler to write a list manually. Here it is:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16012 @vindex top-of-ranges
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16013
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16014 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16015 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16016 (defvar top-of-ranges
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16017 '(10 20 30 40 50
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16018 60 70 80 90 100
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16019 110 120 130 140 150
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16020 160 170 180 190 200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16021 210 220 230 240 250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16022 260 270 280 290 300)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16023 "List specifying ranges for `defuns-per-range'.")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16024 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16025 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16026
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16027 To change the ranges, we edit this list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16028
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16029 Next, we need to write the function that creates the list of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16030 number of definitions within each range. Clearly, this function must
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16031 take the @code{sorted-lengths} and the @code{top-of-ranges} lists
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16032 as arguments.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16033
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16034 The @code{defuns-per-range} function must do two things again and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16035 again: it must count the number of definitions within a range
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16036 specified by the current top-of-range value; and it must shift to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16037 next higher value in the @code{top-of-ranges} list after counting the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16038 number of definitions in the current range. Since each of these
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16039 actions is repetitive, we can use @code{while} loops for the job.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16040 One loop counts the number of definitions in the range defined by the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16041 current top-of-range value, and the other loop selects each of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16042 top-of-range values in turn.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16043
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16044 Several entries of the @code{sorted-lengths} list are counted for each
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16045 range; this means that the loop for the @code{sorted-lengths} list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16046 will be inside the loop for the @code{top-of-ranges} list, like a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16047 small gear inside a big gear.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16048
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16049 The inner loop counts the number of definitions within the range. It
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16050 is a simple counting loop of the type we have seen before.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16051 (@xref{Incrementing Loop, , A loop with an incrementing counter}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16052 The true-or-false test of the loop tests whether the value from the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16053 @code{sorted-lengths} list is smaller than the current value of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16054 top of the range. If it is, the function increments the counter and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16055 tests the next value from the @code{sorted-lengths} list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16056
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16057 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16058 The inner loop looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16059
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16060 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16061 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16062 (while @var{length-element-smaller-than-top-of-range}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16063 (setq number-within-range (1+ number-within-range))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16064 (setq sorted-lengths (cdr sorted-lengths)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16065 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16066 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16067
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16068 The outer loop must start with the lowest value of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16069 @code{top-of-ranges} list, and then be set to each of the succeeding
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16070 higher values in turn. This can be done with a loop like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16071
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16072 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16073 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16074 (while top-of-ranges
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16075 @var{body-of-loop}@dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16076 (setq top-of-ranges (cdr top-of-ranges)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16077 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16078 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16079
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16080 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16081 Put together, the two loops look like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16082
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16083 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16084 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16085 (while top-of-ranges
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16086
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16087 ;; @r{Count the number of elements within the current range.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16088 (while @var{length-element-smaller-than-top-of-range}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16089 (setq number-within-range (1+ number-within-range))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16090 (setq sorted-lengths (cdr sorted-lengths)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16091
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16092 ;; @r{Move to next range.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16093 (setq top-of-ranges (cdr top-of-ranges)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16094 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16095 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16096
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16097 In addition, in each circuit of the outer loop, Emacs should record
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16098 the number of definitions within that range (the value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16099 @code{number-within-range}) in a list. We can use @code{cons} for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16100 this purpose. (@xref{cons, , @code{cons}}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16101
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16102 The @code{cons} function works fine, except that the list it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16103 constructs will contain the number of definitions for the highest
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16104 range at its beginning and the number of definitions for the lowest
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16105 range at its end. This is because @code{cons} attaches new elements
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16106 of the list to the beginning of the list, and since the two loops are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16107 working their way through the lengths' list from the lower end first,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16108 the @code{defuns-per-range-list} will end up largest number first.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16109 But we will want to print our graph with smallest values first and the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16110 larger later. The solution is to reverse the order of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16111 @code{defuns-per-range-list}. We can do this using the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16112 @code{nreverse} function, which reverses the order of a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16113 @findex nreverse
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16114
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16115 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16116 For example,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16117
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16118 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16119 (nreverse '(1 2 3 4))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16120 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16121
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16122 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16123 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16124 produces:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16125
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16126 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16127 (4 3 2 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16128 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16129
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16130 Note that the @code{nreverse} function is ``destructive''---that is,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16131 it changes the list to which it is applied; this contrasts with the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16132 @code{car} and @code{cdr} functions, which are non-destructive. In
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16133 this case, we do not want the original @code{defuns-per-range-list},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16134 so it does not matter that it is destroyed. (The @code{reverse}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16135 function provides a reversed copy of a list, leaving the original list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16136 as is.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16137 @findex reverse
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16138
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16139 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16140 Put all together, the @code{defuns-per-range} looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16141
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16142 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16143 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16144 (defun defuns-per-range (sorted-lengths top-of-ranges)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16145 "SORTED-LENGTHS defuns in each TOP-OF-RANGES range."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16146 (let ((top-of-range (car top-of-ranges))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16147 (number-within-range 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16148 defuns-per-range-list)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16149 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16150
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16151 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16152 ;; @r{Outer loop.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16153 (while top-of-ranges
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16154 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16155
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16156 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16157 ;; @r{Inner loop.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16158 (while (and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16159 ;; @r{Need number for numeric test.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16160 (car sorted-lengths)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16161 (< (car sorted-lengths) top-of-range))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16162 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16163
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16164 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16165 ;; @r{Count number of definitions within current range.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16166 (setq number-within-range (1+ number-within-range))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16167 (setq sorted-lengths (cdr sorted-lengths)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16168
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16169 ;; @r{Exit inner loop but remain within outer loop.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16170 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16171
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16172 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16173 (setq defuns-per-range-list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16174 (cons number-within-range defuns-per-range-list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16175 (setq number-within-range 0) ; @r{Reset count to zero.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16176 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16177
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16178 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16179 ;; @r{Move to next range.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16180 (setq top-of-ranges (cdr top-of-ranges))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16181 ;; @r{Specify next top of range value.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16182 (setq top-of-range (car top-of-ranges)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16183 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16184
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16185 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16186 ;; @r{Exit outer loop and count the number of defuns larger than}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16187 ;; @r{ the largest top-of-range value.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16188 (setq defuns-per-range-list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16189 (cons
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16190 (length sorted-lengths)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16191 defuns-per-range-list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16192 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16193
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16194 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16195 ;; @r{Return a list of the number of definitions within each range,}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16196 ;; @r{ smallest to largest.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16197 (nreverse defuns-per-range-list)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16198 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16199 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16201 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16202 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16203 The function is straightforward except for one subtle feature. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16204 true-or-false test of the inner loop looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16205
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16206 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16207 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16208 (and (car sorted-lengths)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16209 (< (car sorted-lengths) top-of-range))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16210 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16211 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16212
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16213 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16214 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16215 instead of like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16216
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16217 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16218 (< (car sorted-lengths) top-of-range)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16219 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16220
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16221 The purpose of the test is to determine whether the first item in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16222 @code{sorted-lengths} list is less than the value of the top of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16223 range.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16224
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16225 The simple version of the test works fine unless the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16226 @code{sorted-lengths} list has a @code{nil} value. In that case, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16227 @code{(car sorted-lengths)} expression function returns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16228 @code{nil}. The @code{<} function cannot compare a number to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16229 @code{nil}, which is an empty list, so Emacs signals an error and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16230 stops the function from attempting to continue to execute.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16231
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16232 The @code{sorted-lengths} list always becomes @code{nil} when the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16233 counter reaches the end of the list. This means that any attempt to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16234 use the @code{defuns-per-range} function with the simple version of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16235 the test will fail.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16236
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16237 We solve the problem by using the @code{(car sorted-lengths)}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16238 expression in conjunction with the @code{and} expression. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16239 @code{(car sorted-lengths)} expression returns a non-@code{nil}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16240 value so long as the list has at least one number within it, but
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16241 returns @code{nil} if the list is empty. The @code{and} expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16242 first evaluates the @code{(car sorted-lengths)} expression, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16243 if it is @code{nil}, returns false @emph{without} evaluating the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16244 @code{<} expression. But if the @code{(car sorted-lengths)}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16245 expression returns a non-@code{nil} value, the @code{and} expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16246 evaluates the @code{<} expression, and returns that value as the value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16247 of the @code{and} expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16248
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16249 @c colon in printed section title causes problem in Info cross reference
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16250 This way, we avoid an error.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16251 @iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16252 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16253 (For information about @code{and}, see
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16254 @ref{kill-new function, , The @code{kill-new} function}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16255 @end iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16256 @ifinfo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16257 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16258 (@xref{kill-new function, , The @code{kill-new} function}, for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16259 information about @code{and}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16260 @end ifinfo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16261
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16262 Here is a short test of the @code{defuns-per-range} function. First,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16263 evaluate the expression that binds (a shortened)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16264 @code{top-of-ranges} list to the list of values, then evaluate the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16265 expression for binding the @code{sorted-lengths} list, and then
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16266 evaluate the @code{defuns-per-range} function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16267
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16268 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16269 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16270 ;; @r{(Shorter list than we will use later.)}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16271 (setq top-of-ranges
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16272 '(110 120 130 140 150
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16273 160 170 180 190 200))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16274
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16275 (setq sorted-lengths
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16276 '(85 86 110 116 122 129 154 176 179 200 265 300 300))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16277
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16278 (defuns-per-range sorted-lengths top-of-ranges)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16279 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16280 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16281
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16282 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16283 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16284 The list returned looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16285
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16286 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16287 (2 2 2 0 0 1 0 2 0 0 4)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16288 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16289
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16290 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16291 Indeed, there are two elements of the @code{sorted-lengths} list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16292 smaller than 110, two elements between 110 and 119, two elements
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16293 between 120 and 129, and so on. There are four elements with a value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16294 of 200 or larger.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16295
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16296 @c The next step is to turn this numbers' list into a graph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16297 @node Readying a Graph, Emacs Initialization, Words in a defun, Top
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16298 @chapter Readying a Graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16299 @cindex Readying a graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16300 @cindex Graph prototype
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16301 @cindex Prototype graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16302 @cindex Body of graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16303
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16304 Our goal is to construct a graph showing the numbers of function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16305 definitions of various lengths in the Emacs lisp sources.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16306
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16307 As a practical matter, if you were creating a graph, you would
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16308 probably use a program such as @code{gnuplot} to do the job.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16309 (@code{gnuplot} is nicely integrated into GNU Emacs.) In this case,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16310 however, we create one from scratch, and in the process we will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16311 re-acquaint ourselves with some of what we learned before and learn
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16312 more.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16313
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16314 In this chapter, we will first write a simple graph printing function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16315 This first definition will be a @dfn{prototype}, a rapidly written
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16316 function that enables us to reconnoiter this unknown graph-making
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16317 territory. We will discover dragons, or find that they are myth.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16318 After scouting the terrain, we will feel more confident and enhance
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16319 the function to label the axes automatically.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16320
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16321 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16322 * Columns of a graph::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16323 * graph-body-print:: How to print the body of a graph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16324 * recursive-graph-body-print::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16325 * Printed Axes::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16326 * Line Graph Exercise::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16327 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16328
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16329 @node Columns of a graph, graph-body-print, Readying a Graph, Readying a Graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16330 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16331 @unnumberedsec Printing the Columns of a Graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16332 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16333
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16334 Since Emacs is designed to be flexible and work with all kinds of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16335 terminals, including character-only terminals, the graph will need to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16336 be made from one of the `typewriter' symbols. An asterisk will do; as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16337 we enhance the graph-printing function, we can make the choice of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16338 symbol a user option.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16339
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16340 We can call this function @code{graph-body-print}; it will take a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16341 @code{numbers-list} as its only argument. At this stage, we will not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16342 label the graph, but only print its body.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16343
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16344 The @code{graph-body-print} function inserts a vertical column of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16345 asterisks for each element in the @code{numbers-list}. The height of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16346 each line is determined by the value of that element of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16347 @code{numbers-list}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16348
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16349 Inserting columns is a repetitive act; that means that this function can
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16350 be written either with a @code{while} loop or recursively.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16351
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16352 Our first challenge is to discover how to print a column of asterisks.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16353 Usually, in Emacs, we print characters onto a screen horizontally,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16354 line by line, by typing. We have two routes we can follow: write our
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16355 own column-insertion function or discover whether one exists in Emacs.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16356
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16357 To see whether there is one in Emacs, we can use the @kbd{M-x apropos}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16358 command. This command is like the @kbd{C-h a} (@code{command-apropos})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16359 command, except that the latter finds only those functions that are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16360 commands. The @kbd{M-x apropos} command lists all symbols that match
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16361 a regular expression, including functions that are not interactive.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16362 @findex apropos
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16363
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16364 What we want to look for is some command that prints or inserts
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16365 columns. Very likely, the name of the function will contain either
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16366 the word `print' or the word `insert' or the word `column'.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16367 Therefore, we can simply type @kbd{M-x apropos RET
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16368 print\|insert\|column RET} and look at the result. On my system, this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16369 command once too takes quite some time, and then produced a list of 79
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16370 functions and variables. Now it does not take much time at all and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16371 produces a list of 211 functions and variables. Scanning down the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16372 list, the only function that looks as if it might do the job is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16373 @code{insert-rectangle}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16374
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16375 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16376 Indeed, this is the function we want; its documentation says:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16377
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16378 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16379 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16380 insert-rectangle:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16381 Insert text of RECTANGLE with upper left corner at point.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16382 RECTANGLE's first line is inserted at point,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16383 its second line is inserted at a point vertically under point, etc.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16384 RECTANGLE should be a list of strings.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16385 After this command, the mark is at the upper left corner
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16386 and point is at the lower right corner.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16387 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16388 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16389
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16390 We can run a quick test, to make sure it does what we expect of it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16391
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16392 Here is the result of placing the cursor after the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16393 @code{insert-rectangle} expression and typing @kbd{C-u C-x C-e}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16394 (@code{eval-last-sexp}). The function inserts the strings
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16395 @samp{"first"}, @samp{"second"}, and @samp{"third"} at and below
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16396 point. Also the function returns @code{nil}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16397
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16398 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16399 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16400 (insert-rectangle '("first" "second" "third"))first
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16401 second
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16402 thirdnil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16403 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16404 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16405
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16406 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16407 Of course, we won't be inserting the text of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16408 @code{insert-rectangle} expression itself into the buffer in which we
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16409 are making the graph, but will call the function from our program. We
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16410 shall, however, have to make sure that point is in the buffer at the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16411 place where the @code{insert-rectangle} function will insert its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16412 column of strings.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16413
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16414 If you are reading this in Info, you can see how this works by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16415 switching to another buffer, such as the @file{*scratch*} buffer,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16416 placing point somewhere in the buffer, typing @kbd{M-:}, typing the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16417 @code{insert-rectangle} expression into the minibuffer at the prompt,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16418 and then typing @key{RET}. This causes Emacs to evaluate the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16419 expression in the minibuffer, but to use as the value of point the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16420 position of point in the @file{*scratch*} buffer. (@kbd{M-:} is the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16421 keybinding for @code{eval-expression}. Also, @code{nil} does not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16422 appear in the @file{*scratch*} buffer since the expression is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16423 evaluated in the minibuffer.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16424
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16425 We find when we do this that point ends up at the end of the last
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16426 inserted line---that is to say, this function moves point as a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16427 side-effect. If we were to repeat the command, with point at this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16428 position, the next insertion would be below and to the right of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16429 previous insertion. We don't want this! If we are going to make a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16430 bar graph, the columns need to be beside each other.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16431
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16432 So we discover that each cycle of the column-inserting @code{while}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16433 loop must reposition point to the place we want it, and that place
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16434 will be at the top, not the bottom, of the column. Moreover, we
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16435 remember that when we print a graph, we do not expect all the columns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16436 to be the same height. This means that the top of each column may be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16437 at a different height from the previous one. We cannot simply
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16438 reposition point to the same line each time, but moved over to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16439 right---or perhaps we can@dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16440
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16441 We are planning to make the columns of the bar graph out of asterisks.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16442 The number of asterisks in the column is the number specified by the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16443 current element of the @code{numbers-list}. We need to construct a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16444 list of asterisks of the right length for each call to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16445 @code{insert-rectangle}. If this list consists solely of the requisite
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16446 number of asterisks, then we will have position point the right number
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16447 of lines above the base for the graph to print correctly. This could
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16448 be difficult.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16449
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16450 Alternatively, if we can figure out some way to pass
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16451 @code{insert-rectangle} a list of the same length each time, then we
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16452 can place point on the same line each time, but move it over one
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16453 column to the right for each new column. If we do this, however, some
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16454 of the entries in the list passed to @code{insert-rectangle} must be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16455 blanks rather than asterisks. For example, if the maximum height of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16456 the graph is 5, but the height of the column is 3, then
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16457 @code{insert-rectangle} requires an argument that looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16458
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16459 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16460 (" " " " "*" "*" "*")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16461 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16462
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16463 This last proposal is not so difficult, so long as we can determine
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16464 the column height. There are two ways for us to specify the column
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16465 height: we can arbitrarily state what it will be, which would work
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16466 fine for graphs of that height; or we can search through the list of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16467 numbers and use the maximum height of the list as the maximum height
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16468 of the graph. If the latter operation were difficult, then the former
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16469 procedure would be easiest, but there is a function built into Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16470 that determines the maximum of its arguments. We can use that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16471 function. The function is called @code{max} and it returns the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16472 largest of all its arguments, which must be numbers. Thus, for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16473 example,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16474
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16475 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16476 (max 3 4 6 5 7 3)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16477 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16478
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16479 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16480 returns 7. (A corresponding function called @code{min} returns the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16481 smallest of all its arguments.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16482 @findex max
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16483 @findex min
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16484
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16485 However, we cannot simply call @code{max} on the @code{numbers-list};
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16486 the @code{max} function expects numbers as its argument, not a list of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16487 numbers. Thus, the following expression,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16488
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16489 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16490 (max '(3 4 6 5 7 3))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16491 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16492
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16493 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16494 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16495 produces the following error message;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16496
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16497 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16498 Wrong type of argument: number-or-marker-p, (3 4 6 5 7 3)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16499 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16501 @findex apply
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16502 We need a function that passes a list of arguments to a function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16503 This function is @code{apply}. This function `applies' its first
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16504 argument (a function) to its remaining arguments, the last of which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16505 may be a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16506
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16507 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16508 For example,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16509
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16510 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16511 (apply 'max 3 4 7 3 '(4 8 5))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16512 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16513
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16514 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16515 returns 8.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16516
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16517 (Incidentally, I don't know how you would learn of this function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16518 without a book such as this. It is possible to discover other
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16519 functions, like @code{search-forward} or @code{insert-rectangle}, by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16520 guessing at a part of their names and then using @code{apropos}. Even
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16521 though its base in metaphor is clear---`apply' its first argument to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16522 the rest---I doubt a novice would come up with that particular word
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16523 when using @code{apropos} or other aid. Of course, I could be wrong;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16524 after all, the function was first named by someone who had to invent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16525 it.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16526
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16527 The second and subsequent arguments to @code{apply} are optional, so
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16528 we can use @code{apply} to call a function and pass the elements of a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16529 list to it, like this, which also returns 8:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16530
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16531 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16532 (apply 'max '(4 8 5))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16533 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16534
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16535 This latter way is how we will use @code{apply}. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16536 @code{recursive-lengths-list-many-files} function returns a numbers'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16537 list to which we can apply @code{max} (we could also apply @code{max} to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16538 the sorted numbers' list; it does not matter whether the list is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16539 sorted or not.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16540
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16541 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16542 Hence, the operation for finding the maximum height of the graph is this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16543
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16544 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16545 (setq max-graph-height (apply 'max numbers-list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16546 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16547
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16548 Now we can return to the question of how to create a list of strings
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16549 for a column of the graph. Told the maximum height of the graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16550 and the number of asterisks that should appear in the column, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16551 function should return a list of strings for the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16552 @code{insert-rectangle} command to insert.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16553
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16554 Each column is made up of asterisks or blanks. Since the function is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16555 passed the value of the height of the column and the number of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16556 asterisks in the column, the number of blanks can be found by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16557 subtracting the number of asterisks from the height of the column.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16558 Given the number of blanks and the number of asterisks, two
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16559 @code{while} loops can be used to construct the list:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16560
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16561 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16562 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16563 ;;; @r{First version.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16564 (defun column-of-graph (max-graph-height actual-height)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16565 "Return list of strings that is one column of a graph."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16566 (let ((insert-list nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16567 (number-of-top-blanks
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16568 (- max-graph-height actual-height)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16569 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16570
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16571 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16572 ;; @r{Fill in asterisks.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16573 (while (> actual-height 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16574 (setq insert-list (cons "*" insert-list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16575 (setq actual-height (1- actual-height)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16576 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16577
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16578 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16579 ;; @r{Fill in blanks.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16580 (while (> number-of-top-blanks 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16581 (setq insert-list (cons " " insert-list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16582 (setq number-of-top-blanks
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16583 (1- number-of-top-blanks)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16584 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16585
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16586 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16587 ;; @r{Return whole list.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16588 insert-list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16589 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16590 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16591
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16592 If you install this function and then evaluate the following
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16593 expression you will see that it returns the list as desired:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16594
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16595 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16596 (column-of-graph 5 3)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16597 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16598
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16599 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16600 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16601 returns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16602
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16603 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16604 (" " " " "*" "*" "*")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16605 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16606
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16607 As written, @code{column-of-graph} contains a major flaw: the symbols
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16608 used for the blank and for the marked entries in the column are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16609 `hard-coded' as a space and asterisk. This is fine for a prototype,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16610 but you, or another user, may wish to use other symbols. For example,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16611 in testing the graph function, you many want to use a period in place
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16612 of the space, to make sure the point is being repositioned properly
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16613 each time the @code{insert-rectangle} function is called; or you might
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16614 want to substitute a @samp{+} sign or other symbol for the asterisk.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16615 You might even want to make a graph-column that is more than one
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16616 display column wide. The program should be more flexible. The way to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16617 do that is to replace the blank and the asterisk with two variables
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16618 that we can call @code{graph-blank} and @code{graph-symbol} and define
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16619 those variables separately.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16620
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16621 Also, the documentation is not well written. These considerations
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16622 lead us to the second version of the function:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16623
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16624 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16625 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16626 (defvar graph-symbol "*"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16627 "String used as symbol in graph, usually an asterisk.")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16628 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16629
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16630 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16631 (defvar graph-blank " "
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16632 "String used as blank in graph, usually a blank space.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16633 graph-blank must be the same number of columns wide
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16634 as graph-symbol.")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16635 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16636 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16637
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16638 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16639 (For an explanation of @code{defvar}, see
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16640 @ref{defvar, , Initializing a Variable with @code{defvar}}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16641
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16642 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16643 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16644 ;;; @r{Second version.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16645 (defun column-of-graph (max-graph-height actual-height)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16646 "Return MAX-GRAPH-HEIGHT strings; ACTUAL-HEIGHT are graph-symbols.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16647
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16648 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16649 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16650 The graph-symbols are contiguous entries at the end
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16651 of the list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16652 The list will be inserted as one column of a graph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16653 The strings are either graph-blank or graph-symbol."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16654 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16655
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16656 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16657 (let ((insert-list nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16658 (number-of-top-blanks
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16659 (- max-graph-height actual-height)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16660 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16661
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16662 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16663 ;; @r{Fill in @code{graph-symbols}.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16664 (while (> actual-height 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16665 (setq insert-list (cons graph-symbol insert-list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16666 (setq actual-height (1- actual-height)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16667 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16668
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16669 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16670 ;; @r{Fill in @code{graph-blanks}.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16671 (while (> number-of-top-blanks 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16672 (setq insert-list (cons graph-blank insert-list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16673 (setq number-of-top-blanks
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16674 (1- number-of-top-blanks)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16675
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16676 ;; @r{Return whole list.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16677 insert-list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16678 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16679 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16680
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16681 If we wished, we could rewrite @code{column-of-graph} a third time to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16682 provide optionally for a line graph as well as for a bar graph. This
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16683 would not be hard to do. One way to think of a line graph is that it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16684 is no more than a bar graph in which the part of each bar that is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16685 below the top is blank. To construct a column for a line graph, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16686 function first constructs a list of blanks that is one shorter than
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16687 the value, then it uses @code{cons} to attach a graph symbol to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16688 list; then it uses @code{cons} again to attach the `top blanks' to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16689 the list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16690
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16691 It is easy to see how to write such a function, but since we don't
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16692 need it, we will not do it. But the job could be done, and if it were
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16693 done, it would be done with @code{column-of-graph}. Even more
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16694 important, it is worth noting that few changes would have to be made
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16695 anywhere else. The enhancement, if we ever wish to make it, is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16696 simple.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16697
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16698 Now, finally, we come to our first actual graph printing function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16699 This prints the body of a graph, not the labels for the vertical and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16700 horizontal axes, so we can call this @code{graph-body-print}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16701
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16702 @node graph-body-print, recursive-graph-body-print, Columns of a graph, Readying a Graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16703 @section The @code{graph-body-print} Function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16704 @findex graph-body-print
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16705
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16706 After our preparation in the preceding section, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16707 @code{graph-body-print} function is straightforward. The function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16708 will print column after column of asterisks and blanks, using the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16709 elements of a numbers' list to specify the number of asterisks in each
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16710 column. This is a repetitive act, which means we can use a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16711 decrementing @code{while} loop or recursive function for the job. In
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16712 this section, we will write the definition using a @code{while} loop.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16713
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16714 The @code{column-of-graph} function requires the height of the graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16715 as an argument, so we should determine and record that as a local variable.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16716
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16717 This leads us to the following template for the @code{while} loop
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16718 version of this function:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16719
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16720 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16721 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16722 (defun graph-body-print (numbers-list)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16723 "@var{documentation}@dots{}"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16724 (let ((height @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16725 @dots{}))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16726 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16727
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16728 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16729 (while numbers-list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16730 @var{insert-columns-and-reposition-point}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16731 (setq numbers-list (cdr numbers-list)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16732 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16733 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16734
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16735 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16736 We need to fill in the slots of the template.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16737
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16738 Clearly, we can use the @code{(apply 'max numbers-list)} expression to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16739 determine the height of the graph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16740
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16741 The @code{while} loop will cycle through the @code{numbers-list} one
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16742 element at a time. As it is shortened by the @code{(setq numbers-list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16743 (cdr numbers-list))} expression, the @sc{car} of each instance of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16744 list is the value of the argument for @code{column-of-graph}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16745
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16746 At each cycle of the @code{while} loop, the @code{insert-rectangle}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16747 function inserts the list returned by @code{column-of-graph}. Since
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16748 the @code{insert-rectangle} function moves point to the lower right of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16749 the inserted rectangle, we need to save the location of point at the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16750 time the rectangle is inserted, move back to that position after the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16751 rectangle is inserted, and then move horizontally to the next place
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16752 from which @code{insert-rectangle} is called.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16753
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16754 If the inserted columns are one character wide, as they will be if
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16755 single blanks and asterisks are used, the repositioning command is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16756 simply @code{(forward-char 1)}; however, the width of a column may be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16757 greater than one. This means that the repositioning command should be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16758 written @code{(forward-char symbol-width)}. The @code{symbol-width}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16759 itself is the length of a @code{graph-blank} and can be found using
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16760 the expression @code{(length graph-blank)}. The best place to bind
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16761 the @code{symbol-width} variable to the value of the width of graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16762 column is in the varlist of the @code{let} expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16763
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16764 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16765 These considerations lead to the following function definition:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16766
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16767 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16768 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16769 (defun graph-body-print (numbers-list)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16770 "Print a bar graph of the NUMBERS-LIST.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16771 The numbers-list consists of the Y-axis values."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16772
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16773 (let ((height (apply 'max numbers-list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16774 (symbol-width (length graph-blank))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16775 from-position)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16776 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16777
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16778 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16779 (while numbers-list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16780 (setq from-position (point))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16781 (insert-rectangle
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16782 (column-of-graph height (car numbers-list)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16783 (goto-char from-position)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16784 (forward-char symbol-width)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16785 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16786 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16787 ;; @r{Draw graph column by column.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16788 (sit-for 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16789 (setq numbers-list (cdr numbers-list)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16790 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16791 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16792 ;; @r{Place point for X axis labels.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16793 (forward-line height)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16794 (insert "\n")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16795 ))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16796 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16797 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16798
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16799 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16800 The one unexpected expression in this function is the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16801 @w{@code{(sit-for 0)}} expression in the @code{while} loop. This
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16802 expression makes the graph printing operation more interesting to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16803 watch than it would be otherwise. The expression causes Emacs to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16804 `sit' or do nothing for a zero length of time and then redraw the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16805 screen. Placed here, it causes Emacs to redraw the screen column by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16806 column. Without it, Emacs would not redraw the screen until the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16807 function exits.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16808
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16809 We can test @code{graph-body-print} with a short list of numbers.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16810
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16811 @enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16812 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16813 Install @code{graph-symbol}, @code{graph-blank},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16814 @code{column-of-graph}, which are in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16815 @iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16816 @ref{Readying a Graph, , Readying a Graph},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16817 @end iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16818 @ifinfo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16819 @ref{Columns of a graph},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16820 @end ifinfo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16821 and @code{graph-body-print}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16822
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16823 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16824 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16825 Copy the following expression:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16826
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16827 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16828 (graph-body-print '(1 2 3 4 6 4 3 5 7 6 5 2 3))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16829 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16830
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16831 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16832 Switch to the @file{*scratch*} buffer and place the cursor where you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16833 want the graph to start.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16834
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16835 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16836 Type @kbd{M-:} (@code{eval-expression}).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16837
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16838 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16839 Yank the @code{graph-body-print} expression into the minibuffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16840 with @kbd{C-y} (@code{yank)}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16841
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16842 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16843 Press @key{RET} to evaluate the @code{graph-body-print} expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16844 @end enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16845
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16846 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16847 Emacs will print a graph like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16848
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16849 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16850 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16851 *
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16852 * **
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16853 * ****
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16854 *** ****
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16855 ********* *
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16856 ************
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16857 *************
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16858 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16859 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16860
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16861 @node recursive-graph-body-print, Printed Axes, graph-body-print, Readying a Graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16862 @section The @code{recursive-graph-body-print} Function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16863 @findex recursive-graph-body-print
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16864
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16865 The @code{graph-body-print} function may also be written recursively.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16866 The recursive solution is divided into two parts: an outside `wrapper'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16867 that uses a @code{let} expression to determine the values of several
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16868 variables that need only be found once, such as the maximum height of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16869 the graph, and an inside function that is called recursively to print
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16870 the graph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16871
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16872 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16873 The `wrapper' is uncomplicated:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16874
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16875 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16876 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16877 (defun recursive-graph-body-print (numbers-list)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16878 "Print a bar graph of the NUMBERS-LIST.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16879 The numbers-list consists of the Y-axis values."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16880 (let ((height (apply 'max numbers-list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16881 (symbol-width (length graph-blank))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16882 from-position)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16883 (recursive-graph-body-print-internal
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16884 numbers-list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16885 height
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16886 symbol-width)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16887 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16888 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16889
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16890 The recursive function is a little more difficult. It has four parts:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16891 the `do-again-test', the printing code, the recursive call, and the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16892 `next-step-expression'. The `do-again-test' is a @code{when}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16893 expression that determines whether the @code{numbers-list} contains
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16894 any remaining elements; if it does, the function prints one column of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16895 the graph using the printing code and calls itself again. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16896 function calls itself again according to the value produced by the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16897 `next-step-expression' which causes the call to act on a shorter
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16898 version of the @code{numbers-list}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16899
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16900 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16901 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16902 (defun recursive-graph-body-print-internal
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16903 (numbers-list height symbol-width)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16904 "Print a bar graph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16905 Used within recursive-graph-body-print function."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16906 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16907
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16908 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16909 (when numbers-list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16910 (setq from-position (point))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16911 (insert-rectangle
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16912 (column-of-graph height (car numbers-list)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16913 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16914 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16915 (goto-char from-position)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16916 (forward-char symbol-width)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16917 (sit-for 0) ; @r{Draw graph column by column.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16918 (recursive-graph-body-print-internal
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16919 (cdr numbers-list) height symbol-width)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16920 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16921 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16922
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16923 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16924 After installation, this expression can be tested; here is a sample:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16925
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16926 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16927 (recursive-graph-body-print '(3 2 5 6 7 5 3 4 6 4 3 2 1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16928 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16929
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16930 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16931 Here is what @code{recursive-graph-body-print} produces:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16932
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16933 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16934 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16935 *
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16936 ** *
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16937 **** *
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16938 **** ***
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16939 * *********
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16940 ************
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16941 *************
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16942 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16943 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16944
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16945 Either of these two functions, @code{graph-body-print} or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16946 @code{recursive-graph-body-print}, create the body of a graph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16947
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16948 @node Printed Axes, Line Graph Exercise, recursive-graph-body-print, Readying a Graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16949 @section Need for Printed Axes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16950
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16951 A graph needs printed axes, so you can orient yourself. For a do-once
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16952 project, it may be reasonable to draw the axes by hand using Emacs'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16953 Picture mode; but a graph drawing function may be used more than once.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16954
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16955 For this reason, I have written enhancements to the basic
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16956 @code{print-graph-body} function that automatically print labels for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16957 the horizontal and vertical axes. Since the label printing functions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16958 do not contain much new material, I have placed their description in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16959 an appendix. @xref{Full Graph, , A Graph with Labelled Axes}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16960
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16961 @node Line Graph Exercise, , Printed Axes, Readying a Graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16962 @section Exercise
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16963
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16964 Write a line graph version of the graph printing functions.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16965
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16966 @node Emacs Initialization, Debugging, Readying a Graph, Top
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16967 @chapter Your @file{.emacs} File
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16968 @cindex @file{.emacs} file
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16969 @cindex Customizing your @file{.emacs} file
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16970 @cindex Initialization file
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16971
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16972 ``You don't have to like Emacs to like it'' -- this seemingly
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16973 paradoxical statement is the secret of GNU Emacs. The plain, `out of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16974 the box' Emacs is a generic tool. Most people who use it, customize
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16975 it to suit themselves.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16976
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16977 GNU Emacs is mostly written in Emacs Lisp; this means that by writing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16978 expressions in Emacs Lisp you can change or extend Emacs.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16979
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16980 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16981 * Default Configuration::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16982 * Site-wide Init:: You can write site-wide init files.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16983 * defcustom:: Emacs will write code for you.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16984 * Beginning a .emacs File:: How to write a @code{.emacs file}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16985 * Text and Auto-fill:: Automatically wrap lines.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16986 * Mail Aliases:: Use abbreviations for email addresses.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16987 * Indent Tabs Mode:: Don't use tabs with @TeX{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16988 * Keybindings:: Create some personal keybindings.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16989 * Keymaps:: More about key binding.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16990 * Loading Files:: Load (i.e., evaluate) files automatically.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16991 * Autoload:: Make functions available.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16992 * Simple Extension:: Define a function; bind it to a key.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16993 * X11 Colors:: Colors in X.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16994 * Miscellaneous::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16995 * Mode Line:: How to customize your mode line.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16996 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16997
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16998 @node Default Configuration, Site-wide Init, Emacs Initialization, Emacs Initialization
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16999 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17000 @unnumberedsec Emacs' Default Configuration
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17001 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17002
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17003 There are those who appreciate Emacs' default configuration. After
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17004 all, Emacs starts you in C mode when you edit a C file, starts you in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17005 Fortran mode when you edit a Fortran file, and starts you in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17006 Fundamental mode when you edit an unadorned file. This all makes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17007 sense, if you do not know who is going to use Emacs. Who knows what a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17008 person hopes to do with an unadorned file? Fundamental mode is the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17009 right default for such a file, just as C mode is the right default for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17010 editing C code. (Enough programming languages have syntaxes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17011 that enable them to share or nearly share features, so C mode is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17012 now provided by by CC mode, the `C Collection'.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17013
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17014 But when you do know who is going to use Emacs---you,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17015 yourself---then it makes sense to customize Emacs.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17016
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17017 For example, I seldom want Fundamental mode when I edit an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17018 otherwise undistinguished file; I want Text mode. This is why I
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17019 customize Emacs: so it suits me.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17020
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17021 You can customize and extend Emacs by writing or adapting a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17022 @file{~/.emacs} file. This is your personal initialization file; its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17023 contents, written in Emacs Lisp, tell Emacs what to do.@footnote{You
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17024 may also add @file{.el} to @file{~/.emacs} and call it a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17025 @file{~/.emacs.el} file. In the past, you were forbidden to type the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17026 extra keystrokes that the name @file{~/.emacs.el} requires, but now
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17027 you may. The new format is consistent with the Emacs Lisp file
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17028 naming conventions; the old format saves typing.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17029
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17030 A @file{~/.emacs} file contains Emacs Lisp code. You can write this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17031 code yourself; or you can use Emacs' @code{customize} feature to write
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17032 the code for you. You can combine your own expressions and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17033 auto-written Customize expressions in your @file{.emacs} file.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17034
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17035 (I myself prefer to write my own expressions, except for those,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17036 particularly fonts, that I find easier to manipulate using the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17037 @code{customize} command. I combine the two methods.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17038
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17039 Most of this chapter is about writing expressions yourself. It
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17040 describes a simple @file{.emacs} file; for more information, see
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17041 @ref{Init File, , The Init File, emacs, The GNU Emacs Manual}, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17042 @ref{Init File, , The Init File, elisp, The GNU Emacs Lisp Reference
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17043 Manual}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17044
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17045 @node Site-wide Init, defcustom, Default Configuration, Emacs Initialization
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17046 @section Site-wide Initialization Files
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17047
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17048 @cindex @file{default.el} init file
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17049 @cindex @file{site-init.el} init file
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17050 @cindex @file{site-load.el} init file
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17051 In addition to your personal initialization file, Emacs automatically
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17052 loads various site-wide initialization files, if they exist. These
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17053 have the same form as your @file{.emacs} file, but are loaded by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17054 everyone.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17055
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17056 Two site-wide initialization files, @file{site-load.el} and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17057 @file{site-init.el}, are loaded into Emacs and then `dumped' if a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17058 `dumped' version of Emacs is created, as is most common. (Dumped
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17059 copies of Emacs load more quickly. However, once a file is loaded and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17060 dumped, a change to it does not lead to a change in Emacs unless you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17061 load it yourself or re-dump Emacs. @xref{Building Emacs, , Building
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17062 Emacs, elisp, The GNU Emacs Lisp Reference Manual}, and the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17063 @file{INSTALL} file.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17064
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17065 Three other site-wide initialization files are loaded automatically
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17066 each time you start Emacs, if they exist. These are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17067 @file{site-start.el}, which is loaded @emph{before} your @file{.emacs}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17068 file, and @file{default.el}, and the terminal type file, which are both
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17069 loaded @emph{after} your @file{.emacs} file.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17070
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17071 Settings and definitions in your @file{.emacs} file will overwrite
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17072 conflicting settings and definitions in a @file{site-start.el} file,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17073 if it exists; but the settings and definitions in a @file{default.el}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17074 or terminal type file will overwrite those in your @file{.emacs} file.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17075 (You can prevent interference from a terminal type file by setting
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17076 @code{term-file-prefix} to @code{nil}. @xref{Simple Extension, , A
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17077 Simple Extension}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17078
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17079 @c Rewritten to avoid overfull hbox.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17080 The @file{INSTALL} file that comes in the distribution contains
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17081 descriptions of the @file{site-init.el} and @file{site-load.el} files.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17082
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17083 The @file{loadup.el}, @file{startup.el}, and @file{loaddefs.el} files
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17084 control loading. These files are in the @file{lisp} directory of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17085 Emacs distribution and are worth perusing.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17086
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17087 The @file{loaddefs.el} file contains a good many suggestions as to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17088 what to put into your own @file{.emacs} file, or into a site-wide
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17089 initialization file.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17090
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17091 @node defcustom, Beginning a .emacs File, Site-wide Init, Emacs Initialization
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17092 @section Specifying Variables using @code{defcustom}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17093 @findex defcustom
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17094
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17095 You can specify variables using @code{defcustom} so that you and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17096 others can then use Emacs' @code{customize} feature to set their
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17097 values. (You cannot use @code{customize} to write function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17098 definitions; but you can write @code{defuns} in your @file{.emacs}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17099 file. Indeed, you can write any Lisp expression in your @file{.emacs}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17100 file.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17101
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17102 The @code{customize} feature depends on the @code{defcustom} special
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17103 form. Although you can use @code{defvar} or @code{setq} for variables
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17104 that users set, the @code{defcustom} special form is designed for the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17105 job.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17106
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17107 You can use your knowledge of @code{defvar} for writing the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17108 first three arguments for @code{defcustom}. The first argument to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17109 @code{defcustom} is the name of the variable. The second argument is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17110 the variable's initial value, if any; and this value is set only if
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17111 the value has not already been set. The third argument is the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17112 documentation.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17113
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17114 The fourth and subsequent arguments to @code{defcustom} specify types
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17115 and options; these are not featured in @code{defvar}. (These
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17116 arguments are optional.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17117
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17118 Each of these arguments consists of a keyword followed by a value.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17119 Each keyword starts with the colon character @samp{:}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17120
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17121 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17122 For example, the customizable user option variable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17123 @code{text-mode-hook} looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17124
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17125 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17126 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17127 (defcustom text-mode-hook nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17128 "Normal hook run when entering Text mode and many related modes."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17129 :type 'hook
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17130 :options '(turn-on-auto-fill flyspell-mode)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17131 :group 'data)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17132 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17133 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17134
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17135 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17136 The name of the variable is @code{text-mode-hook}; it has no default
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17137 value; and its documentation string tells you what it does.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17138
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17139 The @code{:type} keyword tells Emacs the kind of data to which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17140 @code{text-mode-hook} should be set and how to display the value in a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17141 Customization buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17142
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17143 The @code{:options} keyword specifies a suggested list of values for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17144 the variable. Usually, @code{:options} applies to a hook.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17145 The list is only a suggestion; it is not exclusive; a person who sets
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17146 the variable may set it to other values; the list shown following the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17147 @code{:options} keyword is intended to offer convenient choices to a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17148 user.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17149
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17150 Finally, the @code{:group} keyword tells the Emacs Customization
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17151 command in which group the variable is located. This tells where to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17152 find it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17153
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17154 The @code{defcustom} function recognizes more than a dozen keywords.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17155 For more information, see @ref{Customization, , Writing Customization
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17156 Definitions, elisp, The GNU Emacs Lisp Reference Manual}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17157
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17158 Consider @code{text-mode-hook} as an example.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17159
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17160 There are two ways to customize this variable. You can use the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17161 customization command or write the appropriate expressions yourself.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17162
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17163 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17164 Using the customization command, you can type:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17165
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17166 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17167 M-x customize
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17168 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17169
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17170 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17171 and find that the group for editing files of data is called `data'.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17172 Enter that group. Text Mode Hook is the first member. You can click
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17173 on its various options, such as @code{turn-on-auto-fill}, to set the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17174 values. After you click on the button to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17175
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17176 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17177 Save for Future Sessions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17178 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17179
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17180 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17181 Emacs will write an expression into your @file{.emacs} file.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17182 It will look like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17183
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17184 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17185 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17186 (custom-set-variables
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17187 ;; custom-set-variables was added by Custom.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17188 ;; If you edit it by hand, you could mess it up, so be careful.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17189 ;; Your init file should contain only one such instance.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17190 ;; If there is more than one, they won't work right.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17191 '(text-mode-hook (quote (turn-on-auto-fill text-mode-hook-identify))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17192 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17193 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17194
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17195 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17196 (The @code{text-mode-hook-identify} function tells
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17197 @code{toggle-text-mode-auto-fill} which buffers are in Text mode.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17198 It comes on automatically.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17199
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17200 The @code{custom-set-variables} function works somewhat differently
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17201 than a @code{setq}. While I have never learned the differences, I
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17202 modify the @code{custom-set-variables} expressions in my @file{.emacs}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17203 file by hand: I make the changes in what appears to me to be a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17204 reasonable manner and have not had any problems. Others prefer to use
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17205 the Customization command and let Emacs do the work for them.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17206
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17207 Another @code{custom-set-@dots{}} function is @code{custom-set-faces}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17208 This function sets the various font faces. Over time, I have set a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17209 considerable number of faces. Some of the time, I re-set them using
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17210 @code{customize}; other times, I simply edit the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17211 @code{custom-set-faces} expression in my @file{.emacs} file itself.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17212
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17213 The second way to customize your @code{text-mode-hook} is to set it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17214 yourself in your @file{.emacs} file using code that has nothing to do
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17215 with the @code{custom-set-@dots{}} functions.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17216
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17217 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17218 When you do this, and later use @code{customize}, you will see a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17219 message that says
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17220
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17221 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17222 CHANGED outside Customize; operating on it here may be unreliable.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17223 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17224
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17225 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17226 This message is only a warning. If you click on the button to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17227
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17228 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17229 Save for Future Sessions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17230 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17231
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17232 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17233 Emacs will write a @code{custom-set-@dots{}} expression near the end
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17234 of your @file{.emacs} file that will be evaluated after your
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17235 hand-written expression. It will, therefore, overrule your
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17236 hand-written expression. No harm will be done. When you do this,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17237 however, be careful to remember which expression is active; if you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17238 forget, you may confuse yourself.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17239
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17240 So long as you remember where the values are set, you will have no
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17241 trouble. In any event, the values are always set in your
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17242 initialization file, which is usually called @file{.emacs}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17243
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17244 I myself use @code{customize} for hardly anything. Mostly, I write
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17245 expressions myself.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17246
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17247 @findex defsubst
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17248 @findex defconst
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17249 Incidentally, to be more complete concerning defines: @code{defsubst}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17250 defines an inline function. The syntax is just like that of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17251 @code{defun}. @code{defconst} defines a symbol as a constant. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17252 intent is that neither programs nor users should ever change a value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17253 set by @code{defconst}. (You can change it; the value set is a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17254 variable; but please do not.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17255
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17256 @node Beginning a .emacs File, Text and Auto-fill, defcustom, Emacs Initialization
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17257 @section Beginning a @file{.emacs} File
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17258 @cindex @file{.emacs} file, beginning of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17259
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17260 When you start Emacs, it loads your @file{.emacs} file unless you tell
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17261 it not to by specifying @samp{-q} on the command line. (The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17262 @code{emacs -q} command gives you a plain, out-of-the-box Emacs.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17263
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17264 A @file{.emacs} file contains Lisp expressions. Often, these are no
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17265 more than expressions to set values; sometimes they are function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17266 definitions.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17267
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17268 @xref{Init File, , The Init File @file{~/.emacs}, emacs, The GNU Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17269 Manual}, for a short description of initialization files.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17270
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17271 This chapter goes over some of the same ground, but is a walk among
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17272 extracts from a complete, long-used @file{.emacs} file---my own.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17273
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17274 The first part of the file consists of comments: reminders to myself.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17275 By now, of course, I remember these things, but when I started, I did
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17276 not.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17277
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17278 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17279 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17280 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17281 ;;;; Bob's .emacs file
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17282 ; Robert J. Chassell
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17283 ; 26 September 1985
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17284 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17285 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17286
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17287 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17288 Look at that date! I started this file a long time ago. I have been
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17289 adding to it ever since.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17290
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17291 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17292 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17293 ; Each section in this file is introduced by a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17294 ; line beginning with four semicolons; and each
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17295 ; entry is introduced by a line beginning with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17296 ; three semicolons.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17297 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17298 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17299
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17300 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17301 This describes the usual conventions for comments in Emacs Lisp.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17302 Everything on a line that follows a semicolon is a comment. Two,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17303 three, and four semicolons are used as subsection and section markers.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17304 (@xref{Comments, ,, elisp, The GNU Emacs Lisp Reference Manual}, for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17305 more about comments.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17306
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17307 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17308 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17309 ;;;; The Help Key
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17310 ; Control-h is the help key;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17311 ; after typing control-h, type a letter to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17312 ; indicate the subject about which you want help.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17313 ; For an explanation of the help facility,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17314 ; type control-h two times in a row.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17315 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17316 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17317
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17318 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17319 Just remember: type @kbd{C-h} two times for help.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17320
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17321 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17322 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17323 ; To find out about any mode, type control-h m
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17324 ; while in that mode. For example, to find out
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17325 ; about mail mode, enter mail mode and then type
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17326 ; control-h m.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17327 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17328 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17329
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17330 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17331 `Mode help', as I call this, is very helpful. Usually, it tells you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17332 all you need to know.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17333
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17334 Of course, you don't need to include comments like these in your
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17335 @file{.emacs} file. I included them in mine because I kept forgetting
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17336 about Mode help or the conventions for comments---but I was able to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17337 remember to look here to remind myself.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17338
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17339 @node Text and Auto-fill, Mail Aliases, Beginning a .emacs File, Emacs Initialization
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17340 @section Text and Auto Fill Mode
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17341
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17342 Now we come to the part that `turns on' Text mode and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17343 Auto Fill mode.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17344
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17345 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17346 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17347 ;;; Text mode and Auto Fill mode
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17348 ; The next two lines put Emacs into Text mode
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17349 ; and Auto Fill mode, and are for writers who
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17350 ; want to start writing prose rather than code.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17351 (setq default-major-mode 'text-mode)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17352 (add-hook 'text-mode-hook 'turn-on-auto-fill)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17353 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17354 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17355
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17356 Here is the first part of this @file{.emacs} file that does something
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17357 besides remind a forgetful human!
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17358
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17359 The first of the two lines in parentheses tells Emacs to turn on Text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17360 mode when you find a file, @emph{unless} that file should go into some
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17361 other mode, such as C mode.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17362
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17363 @cindex Per-buffer, local variables list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17364 @cindex Local variables list, per-buffer,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17365 @cindex Automatic mode selection
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17366 @cindex Mode selection, automatic
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17367 When Emacs reads a file, it looks at the extension to the file name,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17368 if any. (The extension is the part that comes after a @samp{.}.) If
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17369 the file ends with a @samp{.c} or @samp{.h} extension then Emacs turns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17370 on C mode. Also, Emacs looks at first nonblank line of the file; if
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17371 the line says @w{@samp{-*- C -*-}}, Emacs turns on C mode. Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17372 possesses a list of extensions and specifications that it uses
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17373 automatically. In addition, Emacs looks near the last page for a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17374 per-buffer, ``local variables list'', if any.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17375
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17376 @ifinfo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17377 @xref{Choosing Modes, , How Major Modes are Chosen, emacs, The GNU
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17378 Emacs Manual}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17379
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17380 @xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17381 Manual}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17382 @end ifinfo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17383 @iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17384 See sections ``How Major Modes are Chosen'' and ``Local Variables in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17385 Files'' in @cite{The GNU Emacs Manual}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17386 @end iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17387
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17388 Now, back to the @file{.emacs} file.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17389
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17390 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17391 Here is the line again; how does it work?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17392
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17393 @cindex Text Mode turned on
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17394 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17395 (setq default-major-mode 'text-mode)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17396 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17397
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17398 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17399 This line is a short, but complete Emacs Lisp expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17400
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17401 We are already familiar with @code{setq}. It sets the following variable,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17402 @code{default-major-mode}, to the subsequent value, which is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17403 @code{text-mode}. The single quote mark before @code{text-mode} tells
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17404 Emacs to deal directly with the @code{text-mode} variable, not with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17405 whatever it might stand for. @xref{set & setq, , Setting the Value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17406 a Variable}, for a reminder of how @code{setq} works. The main point
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17407 is that there is no difference between the procedure you use to set
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17408 a value in your @file{.emacs} file and the procedure you use anywhere
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17409 else in Emacs.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17410
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17411 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17412 Here is the next line:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17413
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17414 @cindex Auto Fill mode turned on
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17415 @findex add-hook
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17416 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17417 (add-hook 'text-mode-hook 'turn-on-auto-fill)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17418 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17419
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17420 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17421 In this line, the @code{add-hook} command adds
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17422 @code{turn-on-auto-fill} to the variable.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17423
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17424 @code{turn-on-auto-fill} is the name of a program, that, you guessed
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17425 it!, turns on Auto Fill mode.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17426
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17427 Every time Emacs turns on Text mode, Emacs runs the commands `hooked'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17428 onto Text mode. So every time Emacs turns on Text mode, Emacs also
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17429 turns on Auto Fill mode.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17430
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17431 In brief, the first line causes Emacs to enter Text mode when you edit a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17432 file, unless the file name extension, a first non-blank line, or local
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17433 variables to tell Emacs otherwise.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17434
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17435 Text mode among other actions, sets the syntax table to work
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17436 conveniently for writers. In Text mode, Emacs considers an apostrophe
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17437 as part of a word like a letter; but Emacs does not consider a period
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17438 or a space as part of a word. Thus, @kbd{M-f} moves you over
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17439 @samp{it's}. On the other hand, in C mode, @kbd{M-f} stops just after
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17440 the @samp{t} of @samp{it's}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17441
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17442 The second line causes Emacs to turn on Auto Fill mode when it turns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17443 on Text mode. In Auto Fill mode, Emacs automatically breaks a line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17444 that is too wide and brings the excessively wide part of the line down
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17445 to the next line. Emacs breaks lines between words, not within them.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17446
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17447 When Auto Fill mode is turned off, lines continue to the right as you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17448 type them. Depending on how you set the value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17449 @code{truncate-lines}, the words you type either disappear off the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17450 right side of the screen, or else are shown, in a rather ugly and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17451 unreadable manner, as a continuation line on the screen.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17452
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17453 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17454 In addition, in this part of my @file{.emacs} file, I tell the Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17455 fill commands to insert two spaces after a colon:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17456
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17457 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17458 (setq colon-double-space t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17459 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17460
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17461 @node Mail Aliases, Indent Tabs Mode, Text and Auto-fill, Emacs Initialization
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17462 @section Mail Aliases
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17463
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17464 Here is a @code{setq} that `turns on' mail aliases, along with more
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17465 reminders.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17466
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17467 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17468 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17469 ;;; Mail mode
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17470 ; To enter mail mode, type `C-x m'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17471 ; To enter RMAIL (for reading mail),
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17472 ; type `M-x rmail'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17473 (setq mail-aliases t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17474 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17475 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17476
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17477 @cindex Mail aliases
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17478 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17479 This @code{setq} command sets the value of the variable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17480 @code{mail-aliases} to @code{t}. Since @code{t} means true, the line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17481 says, in effect, ``Yes, use mail aliases.''
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17482
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17483 Mail aliases are convenient short names for long email addresses or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17484 for lists of email addresses. The file where you keep your `aliases'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17485 is @file{~/.mailrc}. You write an alias like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17486
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17487 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17488 alias geo george@@foobar.wiz.edu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17489 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17490
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17491 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17492 When you write a message to George, address it to @samp{geo}; the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17493 mailer will automatically expand @samp{geo} to the full address.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17494
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17495 @node Indent Tabs Mode, Keybindings, Mail Aliases, Emacs Initialization
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17496 @section Indent Tabs Mode
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17497 @cindex Tabs, preventing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17498 @findex indent-tabs-mode
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17499
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17500 By default, Emacs inserts tabs in place of multiple spaces when it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17501 formats a region. (For example, you might indent many lines of text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17502 all at once with the @code{indent-region} command.) Tabs look fine on
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17503 a terminal or with ordinary printing, but they produce badly indented
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17504 output when you use @TeX{} or Texinfo since @TeX{} ignores tabs.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17505
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17506 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17507 The following turns off Indent Tabs mode:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17508
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17509 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17510 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17511 ;;; Prevent Extraneous Tabs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17512 (setq-default indent-tabs-mode nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17513 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17514 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17515
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17516 Note that this line uses @code{setq-default} rather than the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17517 @code{setq} command that we have seen before. The @code{setq-default}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17518 command sets values only in buffers that do not have their own local
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17519 values for the variable.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17520
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17521 @ifinfo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17522 @xref{Just Spaces, , Tabs vs. Spaces, emacs, The GNU Emacs Manual}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17523
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17524 @xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17525 Manual}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17526 @end ifinfo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17527 @iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17528 See sections ``Tabs vs.@: Spaces'' and ``Local Variables in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17529 Files'' in @cite{The GNU Emacs Manual}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17530 @end iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17531
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17532 @need 1700
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17533 @node Keybindings, Keymaps, Indent Tabs Mode, Emacs Initialization
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17534 @section Some Keybindings
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17535
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17536 Now for some personal keybindings:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17537
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17538 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17539 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17540 ;;; Compare windows
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17541 (global-set-key "\C-cw" 'compare-windows)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17542 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17543 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17544
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17545 @findex compare-windows
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17546 @code{compare-windows} is a nifty command that compares the text in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17547 your current window with text in the next window. It makes the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17548 comparison by starting at point in each window, moving over text in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17549 each window as far as they match. I use this command all the time.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17550
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17551 This also shows how to set a key globally, for all modes.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17552
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17553 @cindex Setting a key globally
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17554 @cindex Global set key
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17555 @cindex Key setting globally
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17556 @findex global-set-key
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17557 The command is @code{global-set-key}. It is followed by the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17558 keybinding. In a @file{.emacs} file, the keybinding is written as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17559 shown: @code{\C-c} stands for `control-c', which means `press the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17560 control key and the @key{c} key at the same time'. The @code{w} means
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17561 `press the @key{w} key'. The keybinding is surrounded by double
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17562 quotation marks. In documentation, you would write this as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17563 @w{@kbd{C-c w}}. (If you were binding a @key{META} key, such as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17564 @kbd{M-c}, rather than a @key{CTRL} key, you would write
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17565 @w{@code{\M-c}} in your @file{.emacs} file. @xref{Init Rebinding, ,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17566 Rebinding Keys in Your Init File, emacs, The GNU Emacs Manual}, for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17567 details.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17568
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17569 The command invoked by the keys is @code{compare-windows}. Note that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17570 @code{compare-windows} is preceded by a single quote; otherwise, Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17571 would first try to evaluate the symbol to determine its value.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17572
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17573 These three things, the double quotation marks, the backslash before
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17574 the @samp{C}, and the single quote mark are necessary parts of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17575 keybinding that I tend to forget. Fortunately, I have come to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17576 remember that I should look at my existing @file{.emacs} file, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17577 adapt what is there.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17578
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17579 As for the keybinding itself: @kbd{C-c w}. This combines the prefix
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17580 key, @kbd{C-c}, with a single character, in this case, @kbd{w}. This
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17581 set of keys, @kbd{C-c} followed by a single character, is strictly
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17582 reserved for individuals' own use. (I call these `own' keys, since
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17583 these are for my own use.) You should always be able to create such a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17584 keybinding for your own use without stomping on someone else's
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17585 keybinding. If you ever write an extension to Emacs, please avoid
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17586 taking any of these keys for public use. Create a key like @kbd{C-c
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17587 C-w} instead. Otherwise, we will run out of `own' keys.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17588
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17589 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17590 Here is another keybinding, with a comment:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17591
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17592 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17593 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17594 ;;; Keybinding for `occur'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17595 ; I use occur a lot, so let's bind it to a key:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17596 (global-set-key "\C-co" 'occur)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17597 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17598 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17599
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17600 @findex occur
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17601 The @code{occur} command shows all the lines in the current buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17602 that contain a match for a regular expression. Matching lines are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17603 shown in a buffer called @file{*Occur*}. That buffer serves as a menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17604 to jump to occurrences.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17605
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17606 @findex global-unset-key
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17607 @cindex Unbinding key
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17608 @cindex Key unbinding
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17609 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17610 Here is how to unbind a key, so it does not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17611 work:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17612
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17613 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17614 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17615 ;;; Unbind `C-x f'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17616 (global-unset-key "\C-xf")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17617 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17618 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17619
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17620 There is a reason for this unbinding: I found I inadvertently typed
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17621 @w{@kbd{C-x f}} when I meant to type @kbd{C-x C-f}. Rather than find a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17622 file, as I intended, I accidentally set the width for filled text,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17623 almost always to a width I did not want. Since I hardly ever reset my
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17624 default width, I simply unbound the key.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17625
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17626 @findex list-buffers, @r{rebound}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17627 @findex buffer-menu, @r{bound to key}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17628 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17629 The following rebinds an existing key:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17630
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17631 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17632 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17633 ;;; Rebind `C-x C-b' for `buffer-menu'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17634 (global-set-key "\C-x\C-b" 'buffer-menu)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17635 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17636 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17637
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17638 By default, @kbd{C-x C-b} runs the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17639 @code{list-buffers} command. This command lists
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17640 your buffers in @emph{another} window. Since I
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17641 almost always want to do something in that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17642 window, I prefer the @code{buffer-menu}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17643 command, which not only lists the buffers,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17644 but moves point into that window.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17645
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17646 @node Keymaps, Loading Files, Keybindings, Emacs Initialization
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17647 @section Keymaps
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17648 @cindex Keymaps
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17649 @cindex Rebinding keys
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17650
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17651 Emacs uses @dfn{keymaps} to record which keys call which commands.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17652 When you use @code{global-set-key} to set the keybinding for a single
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17653 command in all parts of Emacs, you are specifying the keybinding in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17654 @code{current-global-map}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17655
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17656 Specific modes, such as C mode or Text mode, have their own keymaps;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17657 the mode-specific keymaps override the global map that is shared by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17658 all buffers.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17659
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17660 The @code{global-set-key} function binds, or rebinds, the global
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17661 keymap. For example, the following binds the key @kbd{C-x C-b} to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17662 function @code{buffer-menu}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17663
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17664 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17665 (global-set-key "\C-x\C-b" 'buffer-menu)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17666 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17667
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17668 Mode-specific keymaps are bound using the @code{define-key} function,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17669 which takes a specific keymap as an argument, as well as the key and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17670 the command. For example, my @file{.emacs} file contains the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17671 following expression to bind the @code{texinfo-insert-@@group} command
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17672 to @kbd{C-c C-c g}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17673
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17674 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17675 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17676 (define-key texinfo-mode-map "\C-c\C-cg" 'texinfo-insert-@@group)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17677 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17678 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17679
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17680 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17681 The @code{texinfo-insert-@@group} function itself is a little extension
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17682 to Texinfo mode that inserts @samp{@@group} into a Texinfo file. I
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17683 use this command all the time and prefer to type the three strokes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17684 @kbd{C-c C-c g} rather than the six strokes @kbd{@@ g r o u p}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17685 (@samp{@@group} and its matching @samp{@@end group} are commands that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17686 keep all enclosed text together on one page; many multi-line examples
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17687 in this book are surrounded by @samp{@@group @dots{} @@end group}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17688
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17689 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17690 Here is the @code{texinfo-insert-@@group} function definition:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17691
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17692 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17693 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17694 (defun texinfo-insert-@@group ()
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17695 "Insert the string @@group in a Texinfo buffer."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17696 (interactive)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17697 (beginning-of-line)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17698 (insert "@@group\n"))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17699 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17700 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17701
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17702 (Of course, I could have used Abbrev mode to save typing, rather than
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17703 write a function to insert a word; but I prefer key strokes consistent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17704 with other Texinfo mode key bindings.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17705
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17706 You will see numerous @code{define-key} expressions in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17707 @file{loaddefs.el} as well as in the various mode libraries, such as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17708 @file{cc-mode.el} and @file{lisp-mode.el}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17709
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17710 @xref{Key Bindings, , Customizing Key Bindings, emacs, The GNU Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17711 Manual}, and @ref{Keymaps, , Keymaps, elisp, The GNU Emacs Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17712 Reference Manual}, for more information about keymaps.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17713
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17714 @node Loading Files, Autoload, Keymaps, Emacs Initialization
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17715 @section Loading Files
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17716 @cindex Loading files
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17717 @c findex load
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17718
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17719 Many people in the GNU Emacs community have written extensions to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17720 Emacs. As time goes by, these extensions are often included in new
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17721 releases. For example, the Calendar and Diary packages are now part
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17722 of the standard GNU Emacs, as is Calc.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17723
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17724 You can use a @code{load} command to evaluate a complete file and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17725 thereby install all the functions and variables in the file into Emacs.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17726 For example:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17727
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17728 @c (auto-compression-mode t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17729
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17730 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17731 (load "~/emacs/slowsplit")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17732 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17733
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17734 This evaluates, i.e.@: loads, the @file{slowsplit.el} file or if it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17735 exists, the faster, byte compiled @file{slowsplit.elc} file from the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17736 @file{emacs} sub-directory of your home directory. The file contains
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17737 the function @code{split-window-quietly}, which John Robinson wrote in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17738 1989.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17739
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17740 The @code{split-window-quietly} function splits a window with the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17741 minimum of redisplay. I installed it in 1989 because it worked well
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17742 with the slow 1200 baud terminals I was then using. Nowadays, I only
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17743 occasionally come across such a slow connection, but I continue to use
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17744 the function because I like the way it leaves the bottom half of a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17745 buffer in the lower of the new windows and the top half in the upper
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17746 window.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17747
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17748 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17749 To replace the key binding for the default
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17750 @code{split-window-vertically}, you must also unset that key and bind
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17751 the keys to @code{split-window-quietly}, like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17752
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17753 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17754 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17755 (global-unset-key "\C-x2")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17756 (global-set-key "\C-x2" 'split-window-quietly)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17757 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17758 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17759
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17760 @vindex load-path
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17761 If you load many extensions, as I do, then instead of specifying the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17762 exact location of the extension file, as shown above, you can specify
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17763 that directory as part of Emacs' @code{load-path}. Then, when Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17764 loads a file, it will search that directory as well as its default
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17765 list of directories. (The default list is specified in @file{paths.h}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17766 when Emacs is built.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17767
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17768 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17769 The following command adds your @file{~/emacs} directory to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17770 existing load path:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17771
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17772 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17773 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17774 ;;; Emacs Load Path
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17775 (setq load-path (cons "~/emacs" load-path))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17776 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17777 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17778
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17779 Incidentally, @code{load-library} is an interactive interface to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17780 @code{load} function. The complete function looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17781
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17782 @findex load-library
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17783 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17784 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17785 (defun load-library (library)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17786 "Load the library named LIBRARY.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17787 This is an interface to the function `load'."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17788 (interactive
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17789 (list (completing-read "Load library: "
94188
6daf76264055 Update example of complex interactive spec.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 88088
diff changeset
17790 (apply-partially 'locate-file-completion-table
6daf76264055 Update example of complex interactive spec.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 88088
diff changeset
17791 load-path
6daf76264055 Update example of complex interactive spec.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 88088
diff changeset
17792 (get-load-suffixes)))))
83955
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17793 (load library))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17794 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17795 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17796
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17797 The name of the function, @code{load-library}, comes from the use of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17798 `library' as a conventional synonym for `file'. The source for the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17799 @code{load-library} command is in the @file{files.el} library.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17801 Another interactive command that does a slightly different job is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17802 @code{load-file}. @xref{Lisp Libraries, , Libraries of Lisp Code for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17803 Emacs, emacs, The GNU Emacs Manual}, for information on the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17804 distinction between @code{load-library} and this command.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17805
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17806 @node Autoload, Simple Extension, Loading Files, Emacs Initialization
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17807 @section Autoloading
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17808 @findex autoload
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17809
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17810 Instead of installing a function by loading the file that contains it,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17811 or by evaluating the function definition, you can make the function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17812 available but not actually install it until it is first called. This
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17813 is called @dfn{autoloading}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17814
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17815 When you execute an autoloaded function, Emacs automatically evaluates
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17816 the file that contains the definition, and then calls the function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17817
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17818 Emacs starts quicker with autoloaded functions, since their libraries
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17819 are not loaded right away; but you need to wait a moment when you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17820 first use such a function, while its containing file is evaluated.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17821
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17822 Rarely used functions are frequently autoloaded. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17823 @file{loaddefs.el} library contains hundreds of autoloaded functions,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17824 from @code{bookmark-set} to @code{wordstar-mode}. Of course, you may
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17825 come to use a `rare' function frequently. When you do, you should
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17826 load that function's file with a @code{load} expression in your
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17827 @file{.emacs} file.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17828
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17829 In my @file{.emacs} file, I load 14 libraries that contain functions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17830 that would otherwise be autoloaded. (Actually, it would have been
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17831 better to include these files in my `dumped' Emacs, but I forgot.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17832 @xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17833 Reference Manual}, and the @file{INSTALL} file for more about
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17834 dumping.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17835
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17836 You may also want to include autoloaded expressions in your @file{.emacs}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17837 file. @code{autoload} is a built-in function that takes up to five
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17838 arguments, the final three of which are optional. The first argument
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17839 is the name of the function to be autoloaded; the second is the name
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17840 of the file to be loaded. The third argument is documentation for the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17841 function, and the fourth tells whether the function can be called
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17842 interactively. The fifth argument tells what type of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17843 object---@code{autoload} can handle a keymap or macro as well as a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17844 function (the default is a function).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17845
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17846 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17847 Here is a typical example:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17848
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17849 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17850 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17851 (autoload 'html-helper-mode
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17852 "html-helper-mode" "Edit HTML documents" t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17853 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17854 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17855
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17856 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17857 (@code{html-helper-mode} is an older alternative to @code{html-mode},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17858 which is a standard part of the distribution.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17859
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17860 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17861 This expression autoloads the @code{html-helper-mode} function. It
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17862 takes it from the @file{html-helper-mode.el} file (or from the byte
98525
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
17863 compiled version @file{html-helper-mode.elc}, if that exists.) The
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
17864 file must be located in a directory specified by @code{load-path}.
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
17865 The documentation says that this is a mode to help you edit documents
83955
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17866 written in the HyperText Markup Language. You can call this mode
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17867 interactively by typing @kbd{M-x html-helper-mode}. (You need to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17868 duplicate the function's regular documentation in the autoload
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17869 expression because the regular function is not yet loaded, so its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17870 documentation is not available.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17871
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17872 @xref{Autoload, , Autoload, elisp, The GNU Emacs Lisp Reference
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17873 Manual}, for more information.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17874
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17875 @node Simple Extension, X11 Colors, Autoload, Emacs Initialization
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17876 @section A Simple Extension: @code{line-to-top-of-window}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17877 @findex line-to-top-of-window
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17878 @cindex Simple extension in @file{.emacs} file
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17879
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17880 Here is a simple extension to Emacs that moves the line point is on to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17881 the top of the window. I use this all the time, to make text easier
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17882 to read.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17883
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17884 You can put the following code into a separate file and then load it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17885 from your @file{.emacs} file, or you can include it within your
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17886 @file{.emacs} file.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17887
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17888 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17889 Here is the definition:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17890
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17891 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17892 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17893 ;;; Line to top of window;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17894 ;;; replace three keystroke sequence C-u 0 C-l
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17895 (defun line-to-top-of-window ()
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17896 "Move the line point is on to top of window."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17897 (interactive)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17898 (recenter 0))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17899 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17900 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17901
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17902 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17903 Now for the keybinding.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17904
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17905 Nowadays, function keys as well as mouse button events and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17906 non-@sc{ascii} characters are written within square brackets, without
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17907 quotation marks. (In Emacs version 18 and before, you had to write
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17908 different function key bindings for each different make of terminal.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17909
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17910 I bind @code{line-to-top-of-window} to my @key{F6} function key like
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17911 this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17912
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17913 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17914 (global-set-key [f6] 'line-to-top-of-window)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17915 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17916
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17917 For more information, see @ref{Init Rebinding, , Rebinding Keys in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17918 Your Init File, emacs, The GNU Emacs Manual}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17919
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17920 @cindex Conditional 'twixt two versions of Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17921 @cindex Version of Emacs, choosing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17922 @cindex Emacs version, choosing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17923 If you run two versions of GNU Emacs, such as versions 21 and 22, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17924 use one @file{.emacs} file, you can select which code to evaluate with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17925 the following conditional:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17926
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17927 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17928 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17929 (cond
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17930 (= 21 emacs-major-version)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17931 ;; evaluate version 21 code
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17932 ( @dots{} ))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17933 (= 22 emacs-major-version)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17934 ;; evaluate version 22 code
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17935 ( @dots{} )))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17936 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17937 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17938
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17939 For example, in contrast to version 20, more recent versions blink
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17940 their cursors by default. I hate such blinking, as well as other
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17941 features, so I placed the following in my @file{.emacs}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17942 file@footnote{When I start instances of Emacs that do not load my
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17943 @file{.emacs} file or any site file, I also turn off blinking:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17944
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17945 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17946 emacs -q --no-site-file -eval '(blink-cursor-mode nil)'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17947
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17948 @exdent Or nowadays, using an even more sophisticated set of options,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17949
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17950 emacs -Q - D
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17951 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17952 }:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17953
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17954 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17955 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17956 (when (or (= 21 emacs-major-version)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17957 (= 22 emacs-major-version))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17958 (blink-cursor-mode 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17959 ;; Insert newline when you press `C-n' (next-line)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17960 ;; at the end of the buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17961 (setq next-line-add-newlines t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17962 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17963 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17964 ;; Turn on image viewing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17965 (auto-image-file-mode t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17966 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17967 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17968 ;; Turn on menu bar (this bar has text)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17969 ;; (Use numeric argument to turn on)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17970 (menu-bar-mode 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17971 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17972 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17973 ;; Turn off tool bar (this bar has icons)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17974 ;; (Use numeric argument to turn on)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17975 (tool-bar-mode nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17976 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17977 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17978 ;; Turn off tooltip mode for tool bar
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17979 ;; (This mode causes icon explanations to pop up)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17980 ;; (Use numeric argument to turn on)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17981 (tooltip-mode nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17982 ;; If tooltips turned on, make tips appear promptly
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17983 (setq tooltip-delay 0.1) ; default is 0.7 second
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17984 )
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17985 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17986 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17987
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17988 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17989 Alternatively, since @code{blink-cursor-mode} has existed since Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17990 version 21 and is likely to continue, you could write
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17991
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17992 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17993 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17994 (when (>= emacs-major-version 21)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17995 (blink-cursor-mode 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17996 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17997 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17998
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17999 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18000 and add other expressions, too.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18001
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18002
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18003 @node X11 Colors, Miscellaneous, Simple Extension, Emacs Initialization
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18004 @section X11 Colors
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18005
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18006 You can specify colors when you use Emacs with the MIT X Windowing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18007 system.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18008
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18009 I dislike the default colors and specify my own.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18010
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18011 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18012 Here are the expressions in my @file{.emacs}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18013 file that set values:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18014
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18015 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18016 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18017 ;; Set cursor color
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18018 (set-cursor-color "white")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18019
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18020 ;; Set mouse color
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18021 (set-mouse-color "white")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18022
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18023 ;; Set foreground and background
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18024 (set-foreground-color "white")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18025 (set-background-color "darkblue")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18026 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18027
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18028 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18029 ;;; Set highlighting colors for isearch and drag
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18030 (set-face-foreground 'highlight "white")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18031 (set-face-background 'highlight "blue")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18032 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18033
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18034 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18035 (set-face-foreground 'region "cyan")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18036 (set-face-background 'region "blue")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18037 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18038
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18039 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18040 (set-face-foreground 'secondary-selection "skyblue")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18041 (set-face-background 'secondary-selection "darkblue")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18042 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18043
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18044 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18045 ;; Set calendar highlighting colors
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18046 (setq calendar-load-hook
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18047 '(lambda ()
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18048 (set-face-foreground 'diary-face "skyblue")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18049 (set-face-background 'holiday-face "slate blue")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18050 (set-face-foreground 'holiday-face "white")))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18051 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18052 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18053
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18054 The various shades of blue soothe my eye and prevent me from seeing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18055 the screen flicker.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18056
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18057 Alternatively, I could have set my specifications in various X
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18058 initialization files. For example, I could set the foreground,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18059 background, cursor, and pointer (i.e., mouse) colors in my
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18060 @file{~/.Xresources} file like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18061
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18062 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18063 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18064 Emacs*foreground: white
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18065 Emacs*background: darkblue
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18066 Emacs*cursorColor: white
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18067 Emacs*pointerColor: white
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18068 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18069 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18070
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18071 In any event, since it is not part of Emacs, I set the root color of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18072 my X window in my @file{~/.xinitrc} file, like this@footnote{I also
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18073 run more modern window managers, such as Enlightenment, Gnome, or KDE;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18074 in those cases, I often specify an image rather than a plain color.}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18075
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18076 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18077 xsetroot -solid Navy -fg white &
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18078 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18079
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18080 @need 1700
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18081 @node Miscellaneous, Mode Line, X11 Colors, Emacs Initialization
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18082 @section Miscellaneous Settings for a @file{.emacs} File
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18083
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18084 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18085 Here are a few miscellaneous settings:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18086 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18087
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18088 @itemize @minus
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18089 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18090 Set the shape and color of the mouse cursor:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18091
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18092 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18093 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18094 ; Cursor shapes are defined in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18095 ; `/usr/include/X11/cursorfont.h';
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18096 ; for example, the `target' cursor is number 128;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18097 ; the `top_left_arrow' cursor is number 132.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18098 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18099
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18100 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18101 (let ((mpointer (x-get-resource "*mpointer"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18102 "*emacs*mpointer")))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18103 ;; If you have not set your mouse pointer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18104 ;; then set it, otherwise leave as is:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18105 (if (eq mpointer nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18106 (setq mpointer "132")) ; top_left_arrow
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18107 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18108 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18109 (setq x-pointer-shape (string-to-int mpointer))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18110 (set-mouse-color "white"))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18111 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18112 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18113
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18114 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18115 Or you can set the values of a variety of features in an alist, like
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18116 this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18117
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18118 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18119 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18120 (setq-default
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18121 default-frame-alist
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18122 '((cursor-color . "white")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18123 (mouse-color . "white")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18124 (foreground-color . "white")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18125 (background-color . "DodgerBlue4")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18126 ;; (cursor-type . bar)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18127 (cursor-type . box)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18128 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18129 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18130 (tool-bar-lines . 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18131 (menu-bar-lines . 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18132 (width . 80)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18133 (height . 58)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18134 (font .
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18135 "-Misc-Fixed-Medium-R-Normal--20-200-75-75-C-100-ISO8859-1")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18136 ))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18137 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18138 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18139
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18140 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18141 Convert @kbd{@key{CTRL}-h} into @key{DEL} and @key{DEL}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18142 into @kbd{@key{CTRL}-h}.@*
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18143 (Some older keyboards needed this, although I have not seen the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18144 problem recently.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18145
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18146 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18147 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18148 ;; Translate `C-h' to <DEL>.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18149 ; (keyboard-translate ?\C-h ?\C-?)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18150
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18151 ;; Translate <DEL> to `C-h'.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18152 (keyboard-translate ?\C-? ?\C-h)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18153 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18154 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18155
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18156 @item Turn off a blinking cursor!
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18157
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18158 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18159 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18160 (if (fboundp 'blink-cursor-mode)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18161 (blink-cursor-mode -1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18162 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18163 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18164
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18165 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18166 or start GNU Emacs with the command @code{emacs -nbc}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18167
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18168 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18169 @item When using `grep'@*
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18170 @samp{-i}@w{ } Ignore case distinctions@*
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18171 @samp{-n}@w{ } Prefix each line of output with line number@*
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18172 @samp{-H}@w{ } Print the filename for each match.@*
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18173 @samp{-e}@w{ } Protect patterns beginning with a hyphen character, @samp{-}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18174
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18175 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18176 (setq grep-command "grep -i -nH -e ")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18177 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18178
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18179 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18180 @c Evidently, no longer needed in GNU Emacs 22
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18181
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18182 item Automatically uncompress compressed files when visiting them
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18183
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18184 smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18185 (load "uncompress")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18186 end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18187
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18188 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18189
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18190 @item Find an existing buffer, even if it has a different name@*
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18191 This avoids problems with symbolic links.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18192
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18193 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18194 (setq find-file-existing-other-name t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18195 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18196
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18197 @item Set your language environment and default input method
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18198
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18199 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18200 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18201 (set-language-environment "latin-1")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18202 ;; Remember you can enable or disable multilingual text input
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18203 ;; with the @code{toggle-input-method'} (@kbd{C-\}) command
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18204 (setq default-input-method "latin-1-prefix")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18205 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18206 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18207
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18208 If you want to write with Chinese `GB' characters, set this instead:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18209
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18210 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18211 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18212 (set-language-environment "Chinese-GB")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18213 (setq default-input-method "chinese-tonepy")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18214 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18215 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18216 @end itemize
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18217
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18218 @subsubheading Fixing Unpleasant Key Bindings
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18219 @cindex Key bindings, fixing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18220 @cindex Bindings, key, fixing unpleasant
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18221
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18222 Some systems bind keys unpleasantly. Sometimes, for example, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18223 @key{CTRL} key appears in an awkward spot rather than at the far left
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18224 of the home row.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18225
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18226 Usually, when people fix these sorts of keybindings, they do not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18227 change their @file{~/.emacs} file. Instead, they bind the proper keys
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18228 on their consoles with the @code{loadkeys} or @code{install-keymap}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18229 commands in their boot script and then include @code{xmodmap} commands
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18230 in their @file{.xinitrc} or @file{.Xsession} file for X Windows.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18231
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18232 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18233 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18234 For a boot script:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18235
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18236 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18237 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18238 loadkeys /usr/share/keymaps/i386/qwerty/emacs2.kmap.gz
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18239 @exdent or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18240 install-keymap emacs2
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18241 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18242 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18243
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18244 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18245 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18246 For a @file{.xinitrc} or @file{.Xsession} file when the @key{Caps
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18247 Lock} key is at the far left of the home row:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18248
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18249 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18250 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18251 # Bind the key labeled `Caps Lock' to `Control'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18252 # (Such a broken user interface suggests that keyboard manufacturers
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18253 # think that computers are typewriters from 1885.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18254
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18255 xmodmap -e "clear Lock"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18256 xmodmap -e "add Control = Caps_Lock"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18257 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18258 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18259
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18260 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18261 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18262 In a @file{.xinitrc} or @file{.Xsession} file, to convert an @key{ALT}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18263 key to a @key{META} key:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18264
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18265 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18266 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18267 # Some ill designed keyboards have a key labeled ALT and no Meta
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18268 xmodmap -e "keysym Alt_L = Meta_L Alt_L"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18269 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18270 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18271
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18272 @need 1700
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18273 @node Mode Line, , Miscellaneous, Emacs Initialization
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18274 @section A Modified Mode Line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18275 @vindex default-mode-line-format
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18276 @cindex Mode line format
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18277
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18278 Finally, a feature I really like: a modified mode line.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18279
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18280 When I work over a network, I forget which machine I am using. Also,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18281 I tend to I lose track of where I am, and which line point is on.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18282
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18283 So I reset my mode line to look like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18284
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18285 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18286 -:-- foo.texi rattlesnake:/home/bob/ Line 1 (Texinfo Fill) Top
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18287 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18288
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18289 I am visiting a file called @file{foo.texi}, on my machine
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18290 @file{rattlesnake} in my @file{/home/bob} buffer. I am on line 1, in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18291 Texinfo mode, and am at the top of the buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18292
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18293 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18294 My @file{.emacs} file has a section that looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18295
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18296 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18297 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18298 ;; Set a Mode Line that tells me which machine, which directory,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18299 ;; and which line I am on, plus the other customary information.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18300 (setq default-mode-line-format
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18301 (quote
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18302 (#("-" 0 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18303 (help-echo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18304 "mouse-1: select window, mouse-2: delete others ..."))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18305 mode-line-mule-info
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18306 mode-line-modified
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18307 mode-line-frame-identification
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18308 " "
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18309 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18310 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18311 mode-line-buffer-identification
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18312 " "
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18313 (:eval (substring
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18314 (system-name) 0 (string-match "\\..+" (system-name))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18315 ":"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18316 default-directory
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18317 #(" " 0 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18318 (help-echo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18319 "mouse-1: select window, mouse-2: delete others ..."))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18320 (line-number-mode " Line %l ")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18321 global-mode-string
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18322 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18323 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18324 #(" %[(" 0 6
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18325 (help-echo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18326 "mouse-1: select window, mouse-2: delete others ..."))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18327 (:eval (mode-line-mode-name))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18328 mode-line-process
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18329 minor-mode-alist
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18330 #("%n" 0 2 (help-echo "mouse-2: widen" local-map (keymap ...)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18331 ")%] "
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18332 (-3 . "%P")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18333 ;; "-%-"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18334 )))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18335 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18336 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18337
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18338 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18339 Here, I redefine the default mode line. Most of the parts are from
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18340 the original; but I make a few changes. I set the @emph{default} mode
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18341 line format so as to permit various modes, such as Info, to override
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18342 it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18343
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18344 Many elements in the list are self-explanatory:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18345 @code{mode-line-modified} is a variable that tells whether the buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18346 has been modified, @code{mode-name} tells the name of the mode, and so
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18347 on. However, the format looks complicated because of two features we
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18348 have not discussed.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18349
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18350 @cindex Properties, in mode line example
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18351 The first string in the mode line is a dash or hyphen, @samp{-}. In
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18352 the old days, it would have been specified simply as @code{"-"}. But
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18353 nowadays, Emacs can add properties to a string, such as highlighting
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18354 or, as in this case, a help feature. If you place your mouse cursor
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18355 over the hyphen, some help information appears (By default, you must
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18356 wait seven-tenths of a second before the information appears. You can
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18357 change that timing by changing the value of @code{tooltip-delay}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18358
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18359 @need 1000
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18360 The new string format has a special syntax:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18361
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18362 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18363 #("-" 0 1 (help-echo "mouse-1: select window, ..."))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18364 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18365
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18366 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18367 The @code{#(} begins a list. The first element of the list is the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18368 string itself, just one @samp{-}. The second and third
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18369 elements specify the range over which the fourth element applies. A
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18370 range starts @emph{after} a character, so a zero means the range
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18371 starts just before the first character; a 1 means that the range ends
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18372 just after the first character. The third element is the property for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18373 the range. It consists of a property list, a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18374 property name, in this case, @samp{help-echo}, followed by a value, in this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18375 case, a string. The second, third, and fourth elements of this new
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18376 string format can be repeated.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18377
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18378 @xref{Text Properties, , Text Properties, elisp, The GNU Emacs Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18379 Reference Manual}, and see @ref{Mode Line Format, , Mode Line Format,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18380 elisp, The GNU Emacs Lisp Reference Manual}, for more information.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18381
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18382 @code{mode-line-buffer-identification}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18383 displays the current buffer name. It is a list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18384 beginning @code{(#("%12b" 0 4 @dots{}}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18385 The @code{#(} begins the list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18386
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18387 The @samp{"%12b"} displays the current buffer name, using the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18388 @code{buffer-name} function with which we are familiar; the `12'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18389 specifies the maximum number of characters that will be displayed.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18390 When a name has fewer characters, whitespace is added to fill out to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18391 this number. (Buffer names can and often should be longer than 12
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18392 characters; this length works well in a typical 80 column wide
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18393 window.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18394
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18395 @code{:eval} says to evaluate the following form and use the result as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18396 a string to display. In this case, the expression displays the first
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18397 component of the full system name. The end of the first component is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18398 a @samp{.} (`period'), so I use the @code{string-match} function to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18399 tell me the length of the first component. The substring from the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18400 zeroth character to that length is the name of the machine.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18401
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18402 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18403 This is the expression:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18404
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18405 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18406 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18407 (:eval (substring
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18408 (system-name) 0 (string-match "\\..+" (system-name))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18409 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18410 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18411
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18412 @samp{%[} and @samp{%]} cause a pair of square brackets
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18413 to appear for each recursive editing level. @samp{%n} says `Narrow'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18414 when narrowing is in effect. @samp{%P} tells you the percentage of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18415 the buffer that is above the bottom of the window, or `Top', `Bottom',
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18416 or `All'. (A lower case @samp{p} tell you the percentage above the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18417 @emph{top} of the window.) @samp{%-} inserts enough dashes to fill
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18418 out the line.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18419
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18420 Remember, ``You don't have to like Emacs to like it'' --- your own
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18421 Emacs can have different colors, different commands, and different
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18422 keys than a default Emacs.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18423
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18424 On the other hand, if you want to bring up a plain `out of the box'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18425 Emacs, with no customization, type:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18426
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18427 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18428 emacs -q
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18429 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18430
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18431 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18432 This will start an Emacs that does @emph{not} load your
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18433 @file{~/.emacs} initialization file. A plain, default Emacs. Nothing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18434 more.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18435
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18436 @node Debugging, Conclusion, Emacs Initialization, Top
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18437 @chapter Debugging
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18438 @cindex debugging
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18439
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18440 GNU Emacs has two debuggers, @code{debug} and @code{edebug}. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18441 first is built into the internals of Emacs and is always with you;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18442 the second requires that you instrument a function before you can use it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18443
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18444 Both debuggers are described extensively in @ref{Debugging, ,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18445 Debugging Lisp Programs, elisp, The GNU Emacs Lisp Reference Manual}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18446 In this chapter, I will walk through a short example of each.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18447
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18448 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18449 * debug:: How to use the built-in debugger.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18450 * debug-on-entry:: Start debugging when you call a function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18451 * debug-on-quit:: Start debugging when you quit with @kbd{C-g}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18452 * edebug:: How to use Edebug, a source level debugger.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18453 * Debugging Exercises::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18454 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18455
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18456 @node debug, debug-on-entry, Debugging, Debugging
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18457 @section @code{debug}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18458 @findex debug
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18459
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18460 Suppose you have written a function definition that is intended to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18461 return the sum of the numbers 1 through a given number. (This is the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18462 @code{triangle} function discussed earlier. @xref{Decrementing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18463 Example, , Example with Decrementing Counter}, for a discussion.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18464 @c xref{Decrementing Loop,, Loop with a Decrementing Counter}, for a discussion.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18465
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18466 However, your function definition has a bug. You have mistyped
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18467 @samp{1=} for @samp{1-}. Here is the broken definition:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18468
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18469 @findex triangle-bugged
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18470 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18471 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18472 (defun triangle-bugged (number)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18473 "Return sum of numbers 1 through NUMBER inclusive."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18474 (let ((total 0))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18475 (while (> number 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18476 (setq total (+ total number))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18477 (setq number (1= number))) ; @r{Error here.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18478 total))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18479 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18480 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18481
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18482 If you are reading this in Info, you can evaluate this definition in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18483 the normal fashion. You will see @code{triangle-bugged} appear in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18484 echo area.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18485
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18486 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18487 Now evaluate the @code{triangle-bugged} function with an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18488 argument of 4:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18489
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18490 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18491 (triangle-bugged 4)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18492 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18493
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18494 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18495 In a recent GNU Emacs, you will create and enter a @file{*Backtrace*}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18496 buffer that says:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18497
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18498 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18499 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18500 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18501 ---------- Buffer: *Backtrace* ----------
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18502 Debugger entered--Lisp error: (void-function 1=)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18503 (1= number)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18504 (setq number (1= number))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18505 (while (> number 0) (setq total (+ total number))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18506 (setq number (1= number)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18507 (let ((total 0)) (while (> number 0) (setq total ...)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18508 (setq number ...)) total)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18509 triangle-bugged(4)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18510 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18511 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18512 eval((triangle-bugged 4))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18513 eval-last-sexp-1(nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18514 eval-last-sexp(nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18515 call-interactively(eval-last-sexp)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18516 ---------- Buffer: *Backtrace* ----------
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18517 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18518 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18519
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18520 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18521 (I have reformatted this example slightly; the debugger does not fold
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18522 long lines. As usual, you can quit the debugger by typing @kbd{q} in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18523 the @file{*Backtrace*} buffer.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18524
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18525 In practice, for a bug as simple as this, the `Lisp error' line will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18526 tell you what you need to know to correct the definition. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18527 function @code{1=} is `void'.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18528
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18529 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18530 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18531 In GNU Emacs 20 and before, you will see:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18532
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18533 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18534 Symbol's function definition is void:@: 1=
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18535 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18536
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18537 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18538 which has the same meaning as the @file{*Backtrace*} buffer line in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18539 version 21.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18540 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18541
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18542 However, suppose you are not quite certain what is going on?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18543 You can read the complete backtrace.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18544
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18545 In this case, you need to run a recent GNU Emacs, which automatically
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18546 starts the debugger that puts you in the @file{*Backtrace*} buffer; or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18547 else, you need to start the debugger manually as described below.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18548
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18549 Read the @file{*Backtrace*} buffer from the bottom up; it tells you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18550 what Emacs did that led to the error. Emacs made an interactive call
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18551 to @kbd{C-x C-e} (@code{eval-last-sexp}), which led to the evaluation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18552 of the @code{triangle-bugged} expression. Each line above tells you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18553 what the Lisp interpreter evaluated next.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18554
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18555 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18556 The third line from the top of the buffer is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18557
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18558 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18559 (setq number (1= number))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18560 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18561
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18562 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18563 Emacs tried to evaluate this expression; in order to do so, it tried
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18564 to evaluate the inner expression shown on the second line from the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18565 top:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18566
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18567 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18568 (1= number)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18569 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18570
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18571 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18572 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18573 This is where the error occurred; as the top line says:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18574
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18575 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18576 Debugger entered--Lisp error: (void-function 1=)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18577 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18578
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18579 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18580 You can correct the mistake, re-evaluate the function definition, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18581 then run your test again.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18582
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18583 @node debug-on-entry, debug-on-quit, debug, Debugging
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18584 @section @code{debug-on-entry}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18585 @findex debug-on-entry
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18586
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18587 A recent GNU Emacs starts the debugger automatically when your
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18588 function has an error.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18589
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18590 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18591 GNU Emacs version 20 and before did not; it simply
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18592 presented you with an error message. You had to start the debugger
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18593 manually.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18594 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18595
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18596 Incidentally, you can start the debugger manually for all versions of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18597 Emacs; the advantage is that the debugger runs even if you do not have
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18598 a bug in your code. Sometimes your code will be free of bugs!
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18599
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18600 You can enter the debugger when you call the function by calling
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18601 @code{debug-on-entry}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18602
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18603 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18604 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18605 Type:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18606
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18607 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18608 M-x debug-on-entry RET triangle-bugged RET
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18609 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18610
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18611 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18612 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18613 Now, evaluate the following:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18614
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18615 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18616 (triangle-bugged 5)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18617 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18618
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18619 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18620 All versions of Emacs will create a @file{*Backtrace*} buffer and tell
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18621 you that it is beginning to evaluate the @code{triangle-bugged}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18622 function:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18623
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18624 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18625 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18626 ---------- Buffer: *Backtrace* ----------
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18627 Debugger entered--entering a function:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18628 * triangle-bugged(5)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18629 eval((triangle-bugged 5))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18630 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18631 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18632 eval-last-sexp-1(nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18633 eval-last-sexp(nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18634 call-interactively(eval-last-sexp)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18635 ---------- Buffer: *Backtrace* ----------
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18636 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18637 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18638
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18639 In the @file{*Backtrace*} buffer, type @kbd{d}. Emacs will evaluate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18640 the first expression in @code{triangle-bugged}; the buffer will look
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18641 like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18642
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18643 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18644 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18645 ---------- Buffer: *Backtrace* ----------
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18646 Debugger entered--beginning evaluation of function call form:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18647 * (let ((total 0)) (while (> number 0) (setq total ...)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18648 (setq number ...)) total)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18649 * triangle-bugged(5)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18650 eval((triangle-bugged 5))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18651 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18652 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18653 eval-last-sexp-1(nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18654 eval-last-sexp(nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18655 call-interactively(eval-last-sexp)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18656 ---------- Buffer: *Backtrace* ----------
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18657 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18658 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18659
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18660 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18661 Now, type @kbd{d} again, eight times, slowly. Each time you type
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18662 @kbd{d}, Emacs will evaluate another expression in the function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18663 definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18664
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18665 @need 1750
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18666 Eventually, the buffer will look like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18667
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18668 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18669 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18670 ---------- Buffer: *Backtrace* ----------
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18671 Debugger entered--beginning evaluation of function call form:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18672 * (setq number (1= number))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18673 * (while (> number 0) (setq total (+ total number))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18674 (setq number (1= number)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18675 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18676 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18677 * (let ((total 0)) (while (> number 0) (setq total ...)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18678 (setq number ...)) total)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18679 * triangle-bugged(5)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18680 eval((triangle-bugged 5))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18681 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18682 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18683 eval-last-sexp-1(nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18684 eval-last-sexp(nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18685 call-interactively(eval-last-sexp)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18686 ---------- Buffer: *Backtrace* ----------
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18687 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18688 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18689
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18690 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18691 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18692 Finally, after you type @kbd{d} two more times, Emacs will reach the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18693 error, and the top two lines of the @file{*Backtrace*} buffer will look
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18694 like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18695
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18696 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18697 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18698 ---------- Buffer: *Backtrace* ----------
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18699 Debugger entered--Lisp error: (void-function 1=)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18700 * (1= number)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18701 @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18702 ---------- Buffer: *Backtrace* ----------
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18703 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18704 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18705
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18706 By typing @kbd{d}, you were able to step through the function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18707
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18708 You can quit a @file{*Backtrace*} buffer by typing @kbd{q} in it; this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18709 quits the trace, but does not cancel @code{debug-on-entry}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18710
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18711 @findex cancel-debug-on-entry
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18712 To cancel the effect of @code{debug-on-entry}, call
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18713 @code{cancel-debug-on-entry} and the name of the function, like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18714
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18715 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18716 M-x cancel-debug-on-entry RET triangle-bugged RET
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18717 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18718
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18719 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18720 (If you are reading this in Info, cancel @code{debug-on-entry} now.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18721
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18722 @node debug-on-quit, edebug, debug-on-entry, Debugging
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18723 @section @code{debug-on-quit} and @code{(debug)}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18724
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18725 In addition to setting @code{debug-on-error} or calling @code{debug-on-entry},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18726 there are two other ways to start @code{debug}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18727
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18728 @findex debug-on-quit
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18729 You can start @code{debug} whenever you type @kbd{C-g}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18730 (@code{keyboard-quit}) by setting the variable @code{debug-on-quit} to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18731 @code{t}. This is useful for debugging infinite loops.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18732
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18733 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18734 @cindex @code{(debug)} in code
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18735 Or, you can insert a line that says @code{(debug)} into your code
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18736 where you want the debugger to start, like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18737
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18738 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18739 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18740 (defun triangle-bugged (number)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18741 "Return sum of numbers 1 through NUMBER inclusive."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18742 (let ((total 0))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18743 (while (> number 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18744 (setq total (+ total number))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18745 (debug) ; @r{Start debugger.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18746 (setq number (1= number))) ; @r{Error here.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18747 total))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18748 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18749 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18750
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18751 The @code{debug} function is described in detail in @ref{Debugger, ,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18752 The Lisp Debugger, elisp, The GNU Emacs Lisp Reference Manual}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18753
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18754 @node edebug, Debugging Exercises, debug-on-quit, Debugging
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18755 @section The @code{edebug} Source Level Debugger
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18756 @cindex Source level debugger
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18757 @findex edebug
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18758
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18759 Edebug is a source level debugger. Edebug normally displays the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18760 source of the code you are debugging, with an arrow at the left that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18761 shows which line you are currently executing.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18762
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18763 You can walk through the execution of a function, line by line, or run
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18764 quickly until reaching a @dfn{breakpoint} where execution stops.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18765
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18766 Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18767 Lisp Reference Manual}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18768
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18769 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18770 Here is a bugged function definition for @code{triangle-recursively}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18771 @xref{Recursive triangle function, , Recursion in place of a counter},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18772 for a review of it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18773
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18774 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18775 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18776 (defun triangle-recursively-bugged (number)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18777 "Return sum of numbers 1 through NUMBER inclusive.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18778 Uses recursion."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18779 (if (= number 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18780 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18781 (+ number
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18782 (triangle-recursively-bugged
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18783 (1= number))))) ; @r{Error here.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18784 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18785 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18786
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18787 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18788 Normally, you would install this definition by positioning your cursor
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18789 after the function's closing parenthesis and typing @kbd{C-x C-e}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18790 (@code{eval-last-sexp}) or else by positioning your cursor within the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18791 definition and typing @kbd{C-M-x} (@code{eval-defun}). (By default,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18792 the @code{eval-defun} command works only in Emacs Lisp mode or in Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18793 Interactive mode.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18794
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18795 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18796 However, to prepare this function definition for Edebug, you must
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18797 first @dfn{instrument} the code using a different command. You can do
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18798 this by positioning your cursor within or just after the definition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18799 and typing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18801 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18802 M-x edebug-defun RET
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18803 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18804
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18805 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18806 This will cause Emacs to load Edebug automatically if it is not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18807 already loaded, and properly instrument the function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18808
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18809 After instrumenting the function, place your cursor after the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18810 following expression and type @kbd{C-x C-e} (@code{eval-last-sexp}):
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18811
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18812 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18813 (triangle-recursively-bugged 3)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18814 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18815
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18816 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18817 You will be jumped back to the source for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18818 @code{triangle-recursively-bugged} and the cursor positioned at the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18819 beginning of the @code{if} line of the function. Also, you will see
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18820 an arrowhead at the left hand side of that line. The arrowhead marks
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18821 the line where the function is executing. (In the following examples,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18822 we show the arrowhead with @samp{=>}; in a windowing system, you may
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18823 see the arrowhead as a solid triangle in the window `fringe'.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18824
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18825 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18826 =>@point{}(if (= number 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18827 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18828
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18829 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18830 @iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18831 In the example, the location of point is displayed with a star,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18832 @samp{@point{}} (in Info, it is displayed as @samp{-!-}).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18833 @end iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18834 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18835 In the example, the location of point is displayed as @samp{@point{}}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18836 (in a printed book, it is displayed with a five pointed star).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18837 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18838
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18839 If you now press @key{SPC}, point will move to the next expression to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18840 be executed; the line will look like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18841
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18842 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18843 =>(if @point{}(= number 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18844 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18845
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18846 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18847 As you continue to press @key{SPC}, point will move from expression to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18848 expression. At the same time, whenever an expression returns a value,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18849 that value will be displayed in the echo area. For example, after you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18850 move point past @code{number}, you will see the following:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18851
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18852 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18853 Result: 3 (#o3, #x3, ?\C-c)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18854 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18855
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18856 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18857 This means the value of @code{number} is 3, which is octal three,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18858 hexadecimal three, and @sc{ascii} `control-c' (the third letter of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18859 alphabet, in case you need to know this information).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18860
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18861 You can continue moving through the code until you reach the line with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18862 the error. Before evaluation, that line looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18863
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18864 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18865 => @point{}(1= number))))) ; @r{Error here.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18866 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18867
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18868 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18869 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18870 When you press @key{SPC} once again, you will produce an error message
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18871 that says:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18872
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18873 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18874 Symbol's function definition is void:@: 1=
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18875 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18876
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18877 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18878 This is the bug.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18879
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18880 Press @kbd{q} to quit Edebug.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18881
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18882 To remove instrumentation from a function definition, simply
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18883 re-evaluate it with a command that does not instrument it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18884 For example, you could place your cursor after the definition's
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18885 closing parenthesis and type @kbd{C-x C-e}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18886
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18887 Edebug does a great deal more than walk with you through a function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18888 You can set it so it races through on its own, stopping only at an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18889 error or at specified stopping points; you can cause it to display the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18890 changing values of various expressions; you can find out how many
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18891 times a function is called, and more.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18892
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18893 Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18894 Lisp Reference Manual}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18895
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18896 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18897 @node Debugging Exercises, , edebug, Debugging
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18898 @section Debugging Exercises
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18899
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18900 @itemize @bullet
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18901 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18902 Install the @code{count-words-region} function and then cause it to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18903 enter the built-in debugger when you call it. Run the command on a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18904 region containing two words. You will need to press @kbd{d} a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18905 remarkable number of times. On your system, is a `hook' called after
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18906 the command finishes? (For information on hooks, see @ref{Command
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18907 Overview, , Command Loop Overview, elisp, The GNU Emacs Lisp Reference
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18908 Manual}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18909
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18910 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18911 Copy @code{count-words-region} into the @file{*scratch*} buffer,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18912 instrument the function for Edebug, and walk through its execution.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18913 The function does not need to have a bug, although you can introduce
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18914 one if you wish. If the function lacks a bug, the walk-through
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18915 completes without problems.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18916
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18917 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18918 While running Edebug, type @kbd{?} to see a list of all the Edebug commands.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18919 (The @code{global-edebug-prefix} is usually @kbd{C-x X}, i.e.@:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18920 @kbd{@key{CTRL}-x} followed by an upper case @kbd{X}; use this prefix
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18921 for commands made outside of the Edebug debugging buffer.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18922
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18923 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18924 In the Edebug debugging buffer, use the @kbd{p}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18925 (@code{edebug-bounce-point}) command to see where in the region the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18926 @code{count-words-region} is working.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18927
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18928 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18929 Move point to some spot further down the function and then type the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18930 @kbd{h} (@code{edebug-goto-here}) command to jump to that location.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18931
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18932 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18933 Use the @kbd{t} (@code{edebug-trace-mode}) command to cause Edebug to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18934 walk through the function on its own; use an upper case @kbd{T} for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18935 @code{edebug-Trace-fast-mode}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18936
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18937 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18938 Set a breakpoint, then run Edebug in Trace mode until it reaches the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18939 stopping point.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18940 @end itemize
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18941
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18942 @node Conclusion, the-the, Debugging, Top
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18943 @chapter Conclusion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18944
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18945 We have now reached the end of this Introduction. You have now
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18946 learned enough about programming in Emacs Lisp to set values, to write
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18947 simple @file{.emacs} files for yourself and your friends, and write
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18948 simple customizations and extensions to Emacs.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18949
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18950 This is a place to stop. Or, if you wish, you can now go onward, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18951 teach yourself.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18952
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18953 You have learned some of the basic nuts and bolts of programming. But
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18954 only some. There are a great many more brackets and hinges that are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18955 easy to use that we have not touched.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18956
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18957 A path you can follow right now lies among the sources to GNU Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18958 and in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18959 @ifnotinfo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18960 @cite{The GNU Emacs Lisp Reference Manual}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18961 @end ifnotinfo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18962 @ifinfo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18963 @ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18964 Emacs Lisp Reference Manual}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18965 @end ifinfo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18966
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18967 The Emacs Lisp sources are an adventure. When you read the sources and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18968 come across a function or expression that is unfamiliar, you need to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18969 figure out or find out what it does.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18970
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18971 Go to the Reference Manual. It is a thorough, complete, and fairly
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18972 easy-to-read description of Emacs Lisp. It is written not only for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18973 experts, but for people who know what you know. (The @cite{Reference
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18974 Manual} comes with the standard GNU Emacs distribution. Like this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18975 introduction, it comes as a Texinfo source file, so you can read it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18976 on-line and as a typeset, printed book.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18977
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18978 Go to the other on-line help that is part of GNU Emacs: the on-line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18979 documentation for all functions and variables, and @code{find-tags},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18980 the program that takes you to sources.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18981
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18982 Here is an example of how I explore the sources. Because of its name,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18983 @file{simple.el} is the file I looked at first, a long time ago. As
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18984 it happens some of the functions in @file{simple.el} are complicated,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18985 or at least look complicated at first sight. The @code{open-line}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18986 function, for example, looks complicated.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18987
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18988 You may want to walk through this function slowly, as we did with the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18989 @code{forward-sentence} function. (@xref{forward-sentence, The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18990 @code{forward-sentence} function}.) Or you may want to skip that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18991 function and look at another, such as @code{split-line}. You don't
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18992 need to read all the functions. According to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18993 @code{count-words-in-defun}, the @code{split-line} function contains
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18994 102 words and symbols.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18995
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18996 Even though it is short, @code{split-line} contains expressions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18997 we have not studied: @code{skip-chars-forward}, @code{indent-to},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18998 @code{current-column} and @code{insert-and-inherit}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18999
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19000 Consider the @code{skip-chars-forward} function. (It is part of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19001 function definition for @code{back-to-indentation}, which is shown in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19002 @ref{Review, , Review}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19003
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19004 In GNU Emacs, you can find out more about @code{skip-chars-forward} by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19005 typing @kbd{C-h f} (@code{describe-function}) and the name of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19006 function. This gives you the function documentation.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19007
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19008 You may be able to guess what is done by a well named function such as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19009 @code{indent-to}; or you can look it up, too. Incidentally, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19010 @code{describe-function} function itself is in @file{help.el}; it is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19011 one of those long, but decipherable functions. You can look up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19012 @code{describe-function} using the @kbd{C-h f} command!
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19013
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19014 In this instance, since the code is Lisp, the @file{*Help*} buffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19015 contains the name of the library containing the function's source.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19016 You can put point over the name of the library and press the RET key,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19017 which in this situation is bound to @code{help-follow}, and be taken
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19018 directly to the source, in the same way as @kbd{M-.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19019 (@code{find-tag}).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19020
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19021 The definition for @code{describe-function} illustrates how to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19022 customize the @code{interactive} expression without using the standard
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19023 character codes; and it shows how to create a temporary buffer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19024
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19025 (The @code{indent-to} function is written in C rather than Emacs Lisp;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19026 it is a `built-in' function. @code{help-follow} takes you to its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19027 source as does @code{find-tag}, when properly set up.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19028
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19029 You can look at a function's source using @code{find-tag}, which is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19030 bound to @kbd{M-.} Finally, you can find out what the Reference
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19031 Manual has to say by visiting the manual in Info, and typing @kbd{i}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19032 (@code{Info-index}) and the name of the function, or by looking up the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19033 function in the index to a printed copy of the manual.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19034
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19035 Similarly, you can find out what is meant by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19036 @code{insert-and-inherit}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19037
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19038 Other interesting source files include @file{paragraphs.el},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19039 @file{loaddefs.el}, and @file{loadup.el}. The @file{paragraphs.el}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19040 file includes short, easily understood functions as well as longer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19041 ones. The @file{loaddefs.el} file contains the many standard
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19042 autoloads and many keymaps. I have never looked at it all; only at
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19043 parts. @file{loadup.el} is the file that loads the standard parts of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19044 Emacs; it tells you a great deal about how Emacs is built.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19045 (@xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19046 Reference Manual}, for more about building.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19047
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19048 As I said, you have learned some nuts and bolts; however, and very
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19049 importantly, we have hardly touched major aspects of programming; I
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19050 have said nothing about how to sort information, except to use the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19051 predefined @code{sort} function; I have said nothing about how to store
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19052 information, except to use variables and lists; I have said nothing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19053 about how to write programs that write programs. These are topics for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19054 another, and different kind of book, a different kind of learning.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19055
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19056 What you have done is learn enough for much practical work with GNU
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19057 Emacs. What you have done is get started. This is the end of a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19058 beginning.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19059
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19060 @c ================ Appendix ================
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19061
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19062 @node the-the, Kill Ring, Conclusion, Top
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19063 @appendix The @code{the-the} Function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19064 @findex the-the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19065 @cindex Duplicated words function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19066 @cindex Words, duplicated
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19067
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19068 Sometimes when you you write text, you duplicate words---as with ``you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19069 you'' near the beginning of this sentence. I find that most
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19070 frequently, I duplicate ``the''; hence, I call the function for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19071 detecting duplicated words, @code{the-the}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19072
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19073 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19074 As a first step, you could use the following regular expression to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19075 search for duplicates:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19076
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19077 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19078 \\(\\w+[ \t\n]+\\)\\1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19079 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19080
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19081 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19082 This regexp matches one or more word-constituent characters followed
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19083 by one or more spaces, tabs, or newlines. However, it does not detect
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19084 duplicated words on different lines, since the ending of the first
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19085 word, the end of the line, is different from the ending of the second
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19086 word, a space. (For more information about regular expressions, see
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19087 @ref{Regexp Search, , Regular Expression Searches}, as well as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19088 @ref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19089 Manual}, and @ref{Regular Expressions, , Regular Expressions, elisp,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19090 The GNU Emacs Lisp Reference Manual}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19091
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19092 You might try searching just for duplicated word-constituent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19093 characters but that does not work since the pattern detects doubles
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19094 such as the two occurrences of `th' in `with the'.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19095
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19096 Another possible regexp searches for word-constituent characters
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19097 followed by non-word-constituent characters, reduplicated. Here,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19098 @w{@samp{\\w+}} matches one or more word-constituent characters and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19099 @w{@samp{\\W*}} matches zero or more non-word-constituent characters.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19100
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19101 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19102 \\(\\(\\w+\\)\\W*\\)\\1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19103 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19104
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19105 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19106 Again, not useful.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19107
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19108 Here is the pattern that I use. It is not perfect, but good enough.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19109 @w{@samp{\\b}} matches the empty string, provided it is at the beginning
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19110 or end of a word; @w{@samp{[^@@ \n\t]+}} matches one or more occurrences of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19111 any characters that are @emph{not} an @@-sign, space, newline, or tab.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19112
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19113 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19114 \\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19115 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19116
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19117 One can write more complicated expressions, but I found that this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19118 expression is good enough, so I use it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19119
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19120 Here is the @code{the-the} function, as I include it in my
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19121 @file{.emacs} file, along with a handy global key binding:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19122
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19123 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19124 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19125 (defun the-the ()
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19126 "Search forward for for a duplicated word."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19127 (interactive)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19128 (message "Searching for for duplicated words ...")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19129 (push-mark)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19130 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19131 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19132 ;; This regexp is not perfect
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19133 ;; but is fairly good over all:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19134 (if (re-search-forward
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19135 "\\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b" nil 'move)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19136 (message "Found duplicated word.")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19137 (message "End of buffer")))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19138 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19139
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19140 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19141 ;; Bind `the-the' to C-c \
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19142 (global-set-key "\C-c\\" 'the-the)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19143 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19144 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19145
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19146 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19147 Here is test text:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19148
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19149 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19150 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19151 one two two three four five
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19152 five six seven
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19153 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19154 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19155
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19156 You can substitute the other regular expressions shown above in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19157 function definition and try each of them on this list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19158
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19159 @node Kill Ring, Full Graph, the-the, Top
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19160 @appendix Handling the Kill Ring
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19161 @cindex Kill ring handling
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19162 @cindex Handling the kill ring
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19163 @cindex Ring, making a list like a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19164
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19165 The kill ring is a list that is transformed into a ring by the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19166 workings of the @code{current-kill} function. The @code{yank} and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19167 @code{yank-pop} commands use the @code{current-kill} function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19168
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19169 This appendix describes the @code{current-kill} function as well as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19170 both the @code{yank} and the @code{yank-pop} commands, but first,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19171 consider the workings of the kill ring.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19172
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19173 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19174 * What the Kill Ring Does::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19175 * current-kill::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19176 * yank:: Paste a copy of a clipped element.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19177 * yank-pop:: Insert element pointed to.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19178 * ring file::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19179 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19180
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19181 @node What the Kill Ring Does, current-kill, Kill Ring, Kill Ring
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19182 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19183 @unnumberedsec What the Kill Ring Does
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19184 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19185
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19186 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19187 The kill ring has a default maximum length of sixty items; this number
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19188 is too large for an explanation. Instead, set it to four. Please
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19189 evaluate the following:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19190
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19191 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19192 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19193 (setq old-kill-ring-max kill-ring-max)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19194 (setq kill-ring-max 4)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19195 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19196 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19197
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19198 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19199 Then, please copy each line of the following indented example into the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19200 kill ring. You may kill each line with @kbd{C-k} or mark it and copy
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19201 it with @kbd{M-w}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19202
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19203 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19204 (In a read-only buffer, such as the @file{*info*} buffer, the kill
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19205 command, @kbd{C-k} (@code{kill-line}), will not remove the text,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19206 merely copy it to the kill ring. However, your machine may beep at
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19207 you. Alternatively, for silence, you may copy the region of each line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19208 with the @kbd{M-w} (@code{kill-ring-save}) command. You must mark
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19209 each line for this command to succeed, but it does not matter at which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19210 end you put point or mark.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19211
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19212 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19213 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19214 Please invoke the calls in order, so that five elements attempt to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19215 fill the kill ring:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19216
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19217 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19218 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19219 first some text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19220 second piece of text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19221 third line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19222 fourth line of text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19223 fifth bit of text
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19224 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19225 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19226
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19227 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19228 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19229 Then find the value of @code{kill-ring} by evaluating
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19230
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19231 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19232 kill-ring
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19233 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19234
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19235 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19236 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19237 It is:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19238
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19239 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19240 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19241 ("fifth bit of text" "fourth line of text"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19242 "third line" "second piece of text")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19243 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19244 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19245
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19246 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19247 The first element, @samp{first some text}, was dropped.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19248
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19249 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19250 To return to the old value for the length of the kill ring, evaluate:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19251
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19252 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19253 (setq kill-ring-max old-kill-ring-max)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19254 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19255
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19256 @node current-kill, yank, What the Kill Ring Does, Kill Ring
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19257 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19258 @appendixsec The @code{current-kill} Function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19259 @findex current-kill
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19260
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19261 The @code{current-kill} function changes the element in the kill ring
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19262 to which @code{kill-ring-yank-pointer} points. (Also, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19263 @code{kill-new} function sets @code{kill-ring-yank-pointer} to point
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19264 to the latest element of the the kill ring. The @code{kill-new}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19265 function is used directly or indirectly by @code{kill-append},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19266 @code{copy-region-as-kill}, @code{kill-ring-save}, @code{kill-line},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19267 and @code{kill-region}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19268
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19269 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19270 * Code for current-kill::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19271 * Understanding current-kill::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19272 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19273
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19274 @node Code for current-kill, Understanding current-kill, current-kill, current-kill
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19275 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19276 @unnumberedsubsec The code for @code{current-kill}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19277 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19278
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19279
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19280 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19281 The @code{current-kill} function is used by @code{yank} and by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19282 @code{yank-pop}. Here is the code for @code{current-kill}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19283
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19284 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19285 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19286 (defun current-kill (n &optional do-not-move)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19287 "Rotate the yanking point by N places, and then return that kill.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19288 If N is zero, `interprogram-paste-function' is set, and calling it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19289 returns a string, then that string is added to the front of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19290 kill ring and returned as the latest kill.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19291 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19292 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19293 If optional arg DO-NOT-MOVE is non-nil, then don't actually move the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19294 yanking point; just return the Nth kill forward."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19295 (let ((interprogram-paste (and (= n 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19296 interprogram-paste-function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19297 (funcall interprogram-paste-function))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19298 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19299 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19300 (if interprogram-paste
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19301 (progn
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19302 ;; Disable the interprogram cut function when we add the new
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19303 ;; text to the kill ring, so Emacs doesn't try to own the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19304 ;; selection, with identical text.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19305 (let ((interprogram-cut-function nil))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19306 (kill-new interprogram-paste))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19307 interprogram-paste)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19308 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19309 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19310 (or kill-ring (error "Kill ring is empty"))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19311 (let ((ARGth-kill-element
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19312 (nthcdr (mod (- n (length kill-ring-yank-pointer))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19313 (length kill-ring))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19314 kill-ring)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19315 (or do-not-move
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19316 (setq kill-ring-yank-pointer ARGth-kill-element))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19317 (car ARGth-kill-element)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19318 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19319 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19320
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19321 Remember also that the @code{kill-new} function sets
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19322 @code{kill-ring-yank-pointer} to the latest element of the the kill
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19323 ring, which means that all the functions that call it set the value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19324 indirectly: @code{kill-append}, @code{copy-region-as-kill},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19325 @code{kill-ring-save}, @code{kill-line}, and @code{kill-region}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19326
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19327 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19328 Here is the line in @code{kill-new}, which is explained in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19329 @ref{kill-new function, , The @code{kill-new} function}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19330
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19331 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19332 (setq kill-ring-yank-pointer kill-ring)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19333 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19334
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19335 @node Understanding current-kill, , Code for current-kill, current-kill
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19336 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19337 @unnumberedsubsec @code{current-kill} in Outline
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19338 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19339
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19340 The @code{current-kill} function looks complex, but as usual, it can
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19341 be understood by taking it apart piece by piece. First look at it in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19342 skeletal form:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19343
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19344 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19345 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19346 (defun current-kill (n &optional do-not-move)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19347 "Rotate the yanking point by N places, and then return that kill."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19348 (let @var{varlist}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19349 @var{body}@dots{})
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19350 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19351 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19352
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19353 This function takes two arguments, one of which is optional. It has a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19354 documentation string. It is @emph{not} interactive.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19355
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19356 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19357 * Body of current-kill::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19358 * Digression concerning error:: How to mislead humans, but not computers.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19359 * Determining the Element::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19360 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19361
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19362 @node Body of current-kill, Digression concerning error, Understanding current-kill, Understanding current-kill
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19363 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19364 @unnumberedsubsubsec The Body of @code{current-kill}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19365 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19366
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19367 The body of the function definition is a @code{let} expression, which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19368 itself has a body as well as a @var{varlist}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19369
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19370 The @code{let} expression declares a variable that will be only usable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19371 within the bounds of this function. This variable is called
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19372 @code{interprogram-paste} and is for copying to another program. It
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19373 is not for copying within this instance of GNU Emacs. Most window
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19374 systems provide a facility for interprogram pasting. Sadly, that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19375 facility usually provides only for the last element. Most windowing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19376 systems have not adopted a ring of many possibilities, even though
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19377 Emacs has provided it for decades.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19378
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19379 The @code{if} expression has two parts, one if there exists
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19380 @code{interprogram-paste} and one if not.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19381
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19382 @need 2000
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19383 Let us consider the `if not' or else-part of the @code{current-kill}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19384 function. (The then-part uses the the @code{kill-new} function, which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19385 we have already described. @xref{kill-new function, , The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19386 @code{kill-new} function}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19387
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19388 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19389 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19390 (or kill-ring (error "Kill ring is empty"))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19391 (let ((ARGth-kill-element
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19392 (nthcdr (mod (- n (length kill-ring-yank-pointer))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19393 (length kill-ring))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19394 kill-ring)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19395 (or do-not-move
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19396 (setq kill-ring-yank-pointer ARGth-kill-element))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19397 (car ARGth-kill-element))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19398 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19399 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19400
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19401 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19402 The code first checks whether the kill ring has content; otherwise it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19403 signals an error.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19404
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19405 @need 1000
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19406 Note that the @code{or} expression is very similar to testing length
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19407 with an @code{if}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19408
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19409 @findex zerop
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19410 @findex error
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19411 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19412 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19413 (if (zerop (length kill-ring)) ; @r{if-part}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19414 (error "Kill ring is empty")) ; @r{then-part}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19415 ;; No else-part
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19416 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19417 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19418
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19419 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19420 If there is not anything in the kill ring, its length must be zero and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19421 an error message sent to the user: @samp{Kill ring is empty}. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19422 @code{current-kill} function uses an @code{or} expression which is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19423 simpler. But an @code{if} expression reminds us what goes on.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19424
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19425 This @code{if} expression uses the function @code{zerop} which returns
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19426 true if the value it is testing is zero. When @code{zerop} tests
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19427 true, the then-part of the @code{if} is evaluated. The then-part is a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19428 list starting with the function @code{error}, which is a function that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19429 is similar to the @code{message} function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19430 (@pxref{message, , The @code{message} Function}) in that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19431 it prints a one-line message in the echo area. However, in addition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19432 to printing a message, @code{error} also stops evaluation of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19433 function within which it is embedded. This means that the rest of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19434 function will not be evaluated if the length of the kill ring is zero.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19435
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19436 Then the @code{current-kill} function selects the element to return.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19437 The selection depends on the number of places that @code{current-kill}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19438 rotates and on where @code{kill-ring-yank-pointer} points.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19439
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19440 Next, either the optional @code{do-not-move} argument is true or the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19441 current value of @code{kill-ring-yank-pointer} is set to point to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19442 list. Finally, another expression returns the first element of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19443 list even if the @code{do-not-move} argument is true.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19444
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19445 @node Digression concerning error, Determining the Element, Body of current-kill, Understanding current-kill
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19446 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19447 @unnumberedsubsubsec Digression about the word `error'
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19448 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19449
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19450 In my opinion, it is slightly misleading, at least to humans, to use
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19451 the term `error' as the name of the @code{error} function. A better
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19452 term would be `cancel'. Strictly speaking, of course, you cannot
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19453 point to, much less rotate a pointer to a list that has no length, so
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19454 from the point of view of the computer, the word `error' is correct.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19455 But a human expects to attempt this sort of thing, if only to find out
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19456 whether the kill ring is full or empty. This is an act of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19457 exploration.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19458
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19459 From the human point of view, the act of exploration and discovery is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19460 not necessarily an error, and therefore should not be labelled as one,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19461 even in the bowels of a computer. As it is, the code in Emacs implies
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19462 that a human who is acting virtuously, by exploring his or her
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19463 environment, is making an error. This is bad. Even though the computer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19464 takes the same steps as it does when there is an `error', a term such as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19465 `cancel' would have a clearer connotation.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19466
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19467 @node Determining the Element, , Digression concerning error, Understanding current-kill
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19468 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19469 @unnumberedsubsubsec Determining the Element
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19470 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19471
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19472 Among other actions, the else-part of the @code{if} expression sets
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19473 the value of @code{kill-ring-yank-pointer} to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19474 @code{ARGth-kill-element} when the kill ring has something in it and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19475 the value of @code{do-not-move} is @code{nil}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19476
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19477 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19478 The code looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19479
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19480 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19481 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19482 (nthcdr (mod (- n (length kill-ring-yank-pointer))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19483 (length kill-ring))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19484 kill-ring)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19485 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19486 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19487
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19488 This needs some examination. Unless it is not supposed to move the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19489 pointer, the @code{current-kill} function changes where
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19490 @code{kill-ring-yank-pointer} points.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19491 That is what the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19492 @w{@code{(setq kill-ring-yank-pointer ARGth-kill-element))}}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19493 expression does. Also, clearly, @code{ARGth-kill-element} is being
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19494 set to be equal to some @sc{cdr} of the kill ring, using the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19495 @code{nthcdr} function that is described in an earlier section.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19496 (@xref{copy-region-as-kill}.) How does it do this?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19497
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19498 As we have seen before (@pxref{nthcdr}), the @code{nthcdr} function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19499 works by repeatedly taking the @sc{cdr} of a list---it takes the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19500 @sc{cdr} of the @sc{cdr} of the @sc{cdr} @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19501
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19502 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19503 The two following expressions produce the same result:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19504
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19505 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19506 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19507 (setq kill-ring-yank-pointer (cdr kill-ring))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19508
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19509 (setq kill-ring-yank-pointer (nthcdr 1 kill-ring))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19510 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19511 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19512
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19513 However, the @code{nthcdr} expression is more complicated. It uses
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19514 the @code{mod} function to determine which @sc{cdr} to select.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19515
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19516 (You will remember to look at inner functions first; indeed, we will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19517 have to go inside the @code{mod}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19518
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19519 The @code{mod} function returns the value of its first argument modulo
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19520 the second; that is to say, it returns the remainder after dividing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19521 the first argument by the second. The value returned has the same
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19522 sign as the second argument.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19523
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19524 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19525 Thus,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19526
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19527 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19528 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19529 (mod 12 4)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19530 @result{} 0 ;; @r{because there is no remainder}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19531 (mod 13 4)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19532 @result{} 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19533 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19534 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19535
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19536 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19537 In this case, the first argument is often smaller than the second.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19538 That is fine.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19539
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19540 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19541 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19542 (mod 0 4)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19543 @result{} 0
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19544 (mod 1 4)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19545 @result{} 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19546 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19547 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19548
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19549 We can guess what the @code{-} function does. It is like @code{+} but
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19550 subtracts instead of adds; the @code{-} function subtracts its second
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19551 argument from its first. Also, we already know what the @code{length}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19552 function does (@pxref{length}). It returns the length of a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19553
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19554 And @code{n} is the name of the required argument to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19555 @code{current-kill} function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19556
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19557 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19558 So when the first argument to @code{nthcdr} is zero, the @code{nthcdr}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19559 expression returns the whole list, as you can see by evaluating the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19560 following:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19561
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19562 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19563 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19564 ;; kill-ring-yank-pointer @r{and} kill-ring @r{have a length of four}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19565 ;; @r{and} (mod (- 0 4) 4) @result{} 0
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19566 (nthcdr (mod (- 0 4) 4)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19567 '("fourth line of text"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19568 "third line"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19569 "second piece of text"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19570 "first some text"))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19571 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19572 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19573
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19574 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19575 When the first argument to the @code{current-kill} function is one,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19576 the @code{nthcdr} expression returns the list without its first
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19577 element.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19578
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19579 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19580 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19581 (nthcdr (mod (- 1 4) 4)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19582 '("fourth line of text"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19583 "third line"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19584 "second piece of text"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19585 "first some text"))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19586 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19587 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19588
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19589 @cindex @samp{global variable} defined
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19590 @cindex @samp{variable, global}, defined
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19591 Incidentally, both @code{kill-ring} and @code{kill-ring-yank-pointer}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19592 are @dfn{global variables}. That means that any expression in Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19593 Lisp can access them. They are not like the local variables set by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19594 @code{let} or like the symbols in an argument list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19595 Local variables can only be accessed
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19596 within the @code{let} that defines them or the function that specifies
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19597 them in an argument list (and within expressions called by them).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19598
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19599 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19600 @c texi2dvi fails when the name of the section is within ifnottex ...
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19601 (@xref{Prevent confusion, , @code{let} Prevents Confusion}, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19602 @ref{defun, , The @code{defun} Special Form}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19603 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19604
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19605 @node yank, yank-pop, current-kill, Kill Ring
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19606 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19607 @appendixsec @code{yank}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19608 @findex yank
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19609
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19610 After learning about @code{current-kill}, the code for the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19611 @code{yank} function is almost easy.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19612
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19613 The @code{yank} function does not use the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19614 @code{kill-ring-yank-pointer} variable directly. It calls
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19615 @code{insert-for-yank} which calls @code{current-kill} which sets the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19616 @code{kill-ring-yank-pointer} variable.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19617
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19618 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19619 The code looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19620
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19621 @c in GNU Emacs 22
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19622 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19623 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19624 (defun yank (&optional arg)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19625 "Reinsert (\"paste\") the last stretch of killed text.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19626 More precisely, reinsert the stretch of killed text most recently
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19627 killed OR yanked. Put point at end, and set mark at beginning.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19628 With just \\[universal-argument] as argument, same but put point at
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19629 beginning (and mark at end). With argument N, reinsert the Nth most
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19630 recently killed stretch of killed text.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19631
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19632 When this command inserts killed text into the buffer, it honors
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19633 `yank-excluded-properties' and `yank-handler' as described in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19634 doc string for `insert-for-yank-1', which see.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19635
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19636 See also the command \\[yank-pop]."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19637 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19638 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19639 (interactive "*P")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19640 (setq yank-window-start (window-start))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19641 ;; If we don't get all the way thru, make last-command indicate that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19642 ;; for the following command.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19643 (setq this-command t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19644 (push-mark (point))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19645 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19646 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19647 (insert-for-yank (current-kill (cond
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19648 ((listp arg) 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19649 ((eq arg '-) -2)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19650 (t (1- arg)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19651 (if (consp arg)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19652 ;; This is like exchange-point-and-mark,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19653 ;; but doesn't activate the mark.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19654 ;; It is cleaner to avoid activation, even though the command
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19655 ;; loop would deactivate the mark because we inserted text.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19656 (goto-char (prog1 (mark t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19657 (set-marker (mark-marker) (point) (current-buffer)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19658 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19659 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19660 ;; If we do get all the way thru, make this-command indicate that.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19661 (if (eq this-command t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19662 (setq this-command 'yank))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19663 nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19664 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19665 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19666
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19667 The key expression is @code{insert-for-yank}, which inserts the string
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19668 returned by @code{current-kill}, but removes some text properties from
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19669 it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19670
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19671 However, before getting to that expression, the function sets the value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19672 of @code{yank-window-start} to the position returned by the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19673 @code{(window-start)} expression, the position at which the display
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19674 currently starts. The @code{yank} function also sets
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19675 @code{this-command} and pushes the mark.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19676
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19677 After it yanks the appropriate element, if the optional argument is a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19678 @sc{cons} rather than a number or nothing, it puts point at beginning
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19679 of the yanked text and mark at its end.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19680
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19681 (The @code{prog1} function is like @code{progn} but returns the value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19682 of its first argument rather than the value of its last argument. Its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19683 first argument is forced to return the buffer's mark as an integer.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19684 You can see the documentation for these functions by placing point
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19685 over them in this buffer and then typing @kbd{C-h f}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19686 (@code{describe-function}) followed by a @kbd{RET}; the default is the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19687 function.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19688
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19689 The last part of the function tells what to do when it succeeds.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19690
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19691 @node yank-pop, ring file, yank, Kill Ring
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19692 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19693 @appendixsec @code{yank-pop}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19694 @findex yank-pop
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19695
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19696 After understanding @code{yank} and @code{current-kill}, you know how
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19697 to approach the @code{yank-pop} function. Leaving out the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19698 documentation to save space, it looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19699
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19700 @c GNU Emacs 22
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19701 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19702 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19703 (defun yank-pop (&optional arg)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19704 "@dots{}"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19705 (interactive "*p")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19706 (if (not (eq last-command 'yank))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19707 (error "Previous command was not a yank"))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19708 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19709 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19710 (setq this-command 'yank)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19711 (unless arg (setq arg 1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19712 (let ((inhibit-read-only t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19713 (before (< (point) (mark t))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19714 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19715 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19716 (if before
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19717 (funcall (or yank-undo-function 'delete-region) (point) (mark t))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19718 (funcall (or yank-undo-function 'delete-region) (mark t) (point)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19719 (setq yank-undo-function nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19720 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19721 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19722 (set-marker (mark-marker) (point) (current-buffer))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19723 (insert-for-yank (current-kill arg))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19724 ;; Set the window start back where it was in the yank command,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19725 ;; if possible.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19726 (set-window-start (selected-window) yank-window-start t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19727 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19728 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19729 (if before
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19730 ;; This is like exchange-point-and-mark,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19731 ;; but doesn't activate the mark.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19732 ;; It is cleaner to avoid activation, even though the command
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19733 ;; loop would deactivate the mark because we inserted text.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19734 (goto-char (prog1 (mark t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19735 (set-marker (mark-marker)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19736 (point)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19737 (current-buffer))))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19738 nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19739 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19740 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19741
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19742 The function is interactive with a small @samp{p} so the prefix
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19743 argument is processed and passed to the function. The command can
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19744 only be used after a previous yank; otherwise an error message is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19745 sent. This check uses the variable @code{last-command} which is set
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19746 by @code{yank} and is discussed elsewhere.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19747 (@xref{copy-region-as-kill}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19748
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19749 The @code{let} clause sets the variable @code{before} to true or false
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19750 depending whether point is before or after mark and then the region
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19751 between point and mark is deleted. This is the region that was just
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19752 inserted by the previous yank and it is this text that will be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19753 replaced.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19754
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19755 @code{funcall} calls its first argument as a function, passing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19756 remaining arguments to it. The first argument is whatever the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19757 @code{or} expression returns. The two remaining arguments are the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19758 positions of point and mark set by the preceding @code{yank} command.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19759
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19760 There is more, but that is the hardest part.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19761
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19762 @node ring file, , yank-pop, Kill Ring
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19763 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19764 @appendixsec The @file{ring.el} File
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19765 @cindex @file{ring.el} file
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19766
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19767 Interestingly, GNU Emacs posses a file called @file{ring.el} that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19768 provides many of the features we just discussed. But functions such
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19769 as @code{kill-ring-yank-pointer} do not use this library, possibly
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19770 because they were written earlier.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19771
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19772 @node Full Graph, Free Software and Free Manuals, Kill Ring, Top
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19773 @appendix A Graph with Labelled Axes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19774
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19775 Printed axes help you understand a graph. They convey scale. In an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19776 earlier chapter (@pxref{Readying a Graph, , Readying a Graph}), we
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19777 wrote the code to print the body of a graph. Here we write the code
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19778 for printing and labelling vertical and horizontal axes, along with the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19779 body itself.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19780
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19781 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19782 * Labelled Example::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19783 * print-graph Varlist:: @code{let} expression in @code{print-graph}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19784 * print-Y-axis:: Print a label for the vertical axis.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19785 * print-X-axis:: Print a horizontal label.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19786 * Print Whole Graph:: The function to print a complete graph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19787 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19788
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19789 @node Labelled Example, print-graph Varlist, Full Graph, Full Graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19790 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19791 @unnumberedsec Labelled Example Graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19792 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19793
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19794 Since insertions fill a buffer to the right and below point, the new
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19795 graph printing function should first print the Y or vertical axis,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19796 then the body of the graph, and finally the X or horizontal axis.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19797 This sequence lays out for us the contents of the function:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19798
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19799 @enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19800 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19801 Set up code.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19802
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19803 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19804 Print Y axis.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19805
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19806 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19807 Print body of graph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19808
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19809 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19810 Print X axis.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19811 @end enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19812
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19813 @need 800
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19814 Here is an example of how a finished graph should look:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19815
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19816 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19817 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19818 10 -
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19819 *
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19820 * *
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19821 * **
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19822 * ***
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19823 5 - * *******
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19824 * *** *******
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19825 *************
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19826 ***************
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19827 1 - ****************
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19828 | | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19829 1 5 10 15
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19830 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19831 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19832
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19833 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19834 In this graph, both the vertical and the horizontal axes are labelled
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19835 with numbers. However, in some graphs, the horizontal axis is time
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19836 and would be better labelled with months, like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19837
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19838 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19839 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19840 5 - *
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19841 * ** *
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19842 *******
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19843 ********** **
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19844 1 - **************
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19845 | ^ |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19846 Jan June Jan
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19847 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19848 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19849
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19850 Indeed, with a little thought, we can easily come up with a variety of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19851 vertical and horizontal labelling schemes. Our task could become
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19852 complicated. But complications breed confusion. Rather than permit
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19853 this, it is better choose a simple labelling scheme for our first
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19854 effort, and to modify or replace it later.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19855
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19856 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19857 These considerations suggest the following outline for the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19858 @code{print-graph} function:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19859
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19860 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19861 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19862 (defun print-graph (numbers-list)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19863 "@var{documentation}@dots{}"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19864 (let ((height @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19865 @dots{}))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19866 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19867 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19868 (print-Y-axis height @dots{} )
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19869 (graph-body-print numbers-list)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19870 (print-X-axis @dots{} )))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19871 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19872 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19873
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19874 We can work on each part of the @code{print-graph} function definition
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19875 in turn.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19876
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19877 @node print-graph Varlist, print-Y-axis, Labelled Example, Full Graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19878 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19879 @appendixsec The @code{print-graph} Varlist
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19880 @cindex @code{print-graph} varlist
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19881
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19882 In writing the @code{print-graph} function, the first task is to write
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19883 the varlist in the @code{let} expression. (We will leave aside for the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19884 moment any thoughts about making the function interactive or about the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19885 contents of its documentation string.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19886
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19887 The varlist should set several values. Clearly, the top of the label
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19888 for the vertical axis must be at least the height of the graph, which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19889 means that we must obtain this information here. Note that the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19890 @code{print-graph-body} function also requires this information. There
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19891 is no reason to calculate the height of the graph in two different
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19892 places, so we should change @code{print-graph-body} from the way we
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19893 defined it earlier to take advantage of the calculation.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19894
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19895 Similarly, both the function for printing the X axis labels and the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19896 @code{print-graph-body} function need to learn the value of the width of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19897 each symbol. We can perform the calculation here and change the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19898 definition for @code{print-graph-body} from the way we defined it in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19899 previous chapter.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19900
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19901 The length of the label for the horizontal axis must be at least as long
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19902 as the graph. However, this information is used only in the function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19903 that prints the horizontal axis, so it does not need to be calculated here.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19904
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19905 These thoughts lead us directly to the following form for the varlist
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19906 in the @code{let} for @code{print-graph}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19907
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19908 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19909 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19910 (let ((height (apply 'max numbers-list)) ; @r{First version.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19911 (symbol-width (length graph-blank)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19912 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19913 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19914
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19915 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19916 As we shall see, this expression is not quite right.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19917
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19918 @need 2000
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19919 @node print-Y-axis, print-X-axis, print-graph Varlist, Full Graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19920 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19921 @appendixsec The @code{print-Y-axis} Function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19922 @cindex Axis, print vertical
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19923 @cindex Y axis printing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19924 @cindex Vertical axis printing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19925 @cindex Print vertical axis
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19926
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19927 The job of the @code{print-Y-axis} function is to print a label for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19928 the vertical axis that looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19929
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19930 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19931 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19932 10 -
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19933
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19934
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19935
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19936
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19937 5 -
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19938
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19939
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19940
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19941 1 -
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19942 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19943 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19944
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19945 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19946 The function should be passed the height of the graph, and then should
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19947 construct and insert the appropriate numbers and marks.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19948
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19949 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19950 * print-Y-axis in Detail::
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19951 * Height of label:: What height for the Y axis?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19952 * Compute a Remainder:: How to compute the remainder of a division.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19953 * Y Axis Element:: Construct a line for the Y axis.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19954 * Y-axis-column:: Generate a list of Y axis labels.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19955 * print-Y-axis Penultimate:: A not quite final version.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19956 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19957
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19958 @node print-Y-axis in Detail, Height of label, print-Y-axis, print-Y-axis
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19959 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19960 @unnumberedsubsec The @code{print-Y-axis} Function in Detail
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19961 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19962
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19963 It is easy enough to see in the figure what the Y axis label should
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19964 look like; but to say in words, and then to write a function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19965 definition to do the job is another matter. It is not quite true to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19966 say that we want a number and a tic every five lines: there are only
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19967 three lines between the @samp{1} and the @samp{5} (lines 2, 3, and 4),
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19968 but four lines between the @samp{5} and the @samp{10} (lines 6, 7, 8,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19969 and 9). It is better to say that we want a number and a tic mark on
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19970 the base line (number 1) and then that we want a number and a tic on
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19971 the fifth line from the bottom and on every line that is a multiple of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19972 five.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19973
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19974 @node Height of label, Compute a Remainder, print-Y-axis in Detail, print-Y-axis
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19975 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19976 @unnumberedsubsec What height should the label be?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19977 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19978
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19979 The next issue is what height the label should be? Suppose the maximum
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19980 height of tallest column of the graph is seven. Should the highest
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19981 label on the Y axis be @samp{5 -}, and should the graph stick up above
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19982 the label? Or should the highest label be @samp{7 -}, and mark the peak
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19983 of the graph? Or should the highest label be @code{10 -}, which is a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19984 multiple of five, and be higher than the topmost value of the graph?
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19985
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19986 The latter form is preferred. Most graphs are drawn within rectangles
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19987 whose sides are an integral number of steps long---5, 10, 15, and so
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19988 on for a step distance of five. But as soon as we decide to use a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19989 step height for the vertical axis, we discover that the simple
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19990 expression in the varlist for computing the height is wrong. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19991 expression is @code{(apply 'max numbers-list)}. This returns the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19992 precise height, not the maximum height plus whatever is necessary to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19993 round up to the nearest multiple of five. A more complex expression
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19994 is required.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19995
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19996 As usual in cases like this, a complex problem becomes simpler if it is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19997 divided into several smaller problems.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19998
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19999 First, consider the case when the highest value of the graph is an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20000 integral multiple of five---when it is 5, 10, 15, or some higher
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20001 multiple of five. We can use this value as the Y axis height.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20002
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20003 A fairly simply way to determine whether a number is a multiple of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20004 five is to divide it by five and see if the division results in a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20005 remainder. If there is no remainder, the number is a multiple of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20006 five. Thus, seven divided by five has a remainder of two, and seven
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20007 is not an integral multiple of five. Put in slightly different
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20008 language, more reminiscent of the classroom, five goes into seven
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20009 once, with a remainder of two. However, five goes into ten twice,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20010 with no remainder: ten is an integral multiple of five.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20011
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20012 @node Compute a Remainder, Y Axis Element, Height of label, print-Y-axis
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20013 @appendixsubsec Side Trip: Compute a Remainder
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20014
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20015 @findex % @r{(remainder function)}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20016 @cindex Remainder function, @code{%}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20017 In Lisp, the function for computing a remainder is @code{%}. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20018 function returns the remainder of its first argument divided by its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20019 second argument. As it happens, @code{%} is a function in Emacs Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20020 that you cannot discover using @code{apropos}: you find nothing if you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20021 type @kbd{M-x apropos @key{RET} remainder @key{RET}}. The only way to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20022 learn of the existence of @code{%} is to read about it in a book such
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20023 as this or in the Emacs Lisp sources.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20024
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20025 You can try the @code{%} function by evaluating the following two
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20026 expressions:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20027
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20028 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20029 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20030 (% 7 5)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20031
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20032 (% 10 5)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20033 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20034 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20035
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20036 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20037 The first expression returns 2 and the second expression returns 0.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20038
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20039 To test whether the returned value is zero or some other number, we
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20040 can use the @code{zerop} function. This function returns @code{t} if
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20041 its argument, which must be a number, is zero.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20042
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20043 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20044 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20045 (zerop (% 7 5))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20046 @result{} nil
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20047
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20048 (zerop (% 10 5))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20049 @result{} t
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20050 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20051 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20052
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20053 Thus, the following expression will return @code{t} if the height
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20054 of the graph is evenly divisible by five:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20055
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20056 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20057 (zerop (% height 5))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20058 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20059
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20060 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20061 (The value of @code{height}, of course, can be found from @code{(apply
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20062 'max numbers-list)}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20063
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20064 On the other hand, if the value of @code{height} is not a multiple of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20065 five, we want to reset the value to the next higher multiple of five.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20066 This is straightforward arithmetic using functions with which we are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20067 already familiar. First, we divide the value of @code{height} by five
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20068 to determine how many times five goes into the number. Thus, five
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20069 goes into twelve twice. If we add one to this quotient and multiply by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20070 five, we will obtain the value of the next multiple of five that is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20071 larger than the height. Five goes into twelve twice. Add one to two,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20072 and multiply by five; the result is fifteen, which is the next multiple
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20073 of five that is higher than twelve. The Lisp expression for this is:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20074
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20075 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20076 (* (1+ (/ height 5)) 5)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20077 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20078
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20079 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20080 For example, if you evaluate the following, the result is 15:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20081
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20082 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20083 (* (1+ (/ 12 5)) 5)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20084 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20085
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20086 All through this discussion, we have been using `five' as the value
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20087 for spacing labels on the Y axis; but we may want to use some other
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20088 value. For generality, we should replace `five' with a variable to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20089 which we can assign a value. The best name I can think of for this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20090 variable is @code{Y-axis-label-spacing}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20091
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20092 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20093 Using this term, and an @code{if} expression, we produce the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20094 following:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20095
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20096 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20097 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20098 (if (zerop (% height Y-axis-label-spacing))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20099 height
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20100 ;; @r{else}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20101 (* (1+ (/ height Y-axis-label-spacing))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20102 Y-axis-label-spacing))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20103 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20104 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20105
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20106 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20107 This expression returns the value of @code{height} itself if the height
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20108 is an even multiple of the value of the @code{Y-axis-label-spacing} or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20109 else it computes and returns a value of @code{height} that is equal to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20110 the next higher multiple of the value of the @code{Y-axis-label-spacing}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20111
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20112 We can now include this expression in the @code{let} expression of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20113 @code{print-graph} function (after first setting the value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20114 @code{Y-axis-label-spacing}):
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20115 @vindex Y-axis-label-spacing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20116
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20117 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20118 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20119 (defvar Y-axis-label-spacing 5
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20120 "Number of lines from one Y axis label to next.")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20121 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20122
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20123 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20124 @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20125 (let* ((height (apply 'max numbers-list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20126 (height-of-top-line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20127 (if (zerop (% height Y-axis-label-spacing))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20128 height
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20129 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20130 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20131 ;; @r{else}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20132 (* (1+ (/ height Y-axis-label-spacing))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20133 Y-axis-label-spacing)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20134 (symbol-width (length graph-blank))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20135 @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20136 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20137 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20138
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20139 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20140 (Note use of the @code{let*} function: the initial value of height is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20141 computed once by the @code{(apply 'max numbers-list)} expression and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20142 then the resulting value of @code{height} is used to compute its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20143 final value. @xref{fwd-para let, , The @code{let*} expression}, for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20144 more about @code{let*}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20145
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20146 @node Y Axis Element, Y-axis-column, Compute a Remainder, print-Y-axis
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20147 @appendixsubsec Construct a Y Axis Element
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20148
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20149 When we print the vertical axis, we want to insert strings such as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20150 @w{@samp{5 -}} and @w{@samp{10 - }} every five lines.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20151 Moreover, we want the numbers and dashes to line up, so shorter
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20152 numbers must be padded with leading spaces. If some of the strings
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20153 use two digit numbers, the strings with single digit numbers must
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20154 include a leading blank space before the number.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20155
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20156 @findex number-to-string
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20157 To figure out the length of the number, the @code{length} function is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20158 used. But the @code{length} function works only with a string, not with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20159 a number. So the number has to be converted from being a number to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20160 being a string. This is done with the @code{number-to-string} function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20161 For example,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20162
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20163 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20164 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20165 (length (number-to-string 35))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20166 @result{} 2
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20167
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20168 (length (number-to-string 100))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20169 @result{} 3
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20170 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20171 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20172
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20173 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20174 (@code{number-to-string} is also called @code{int-to-string}; you will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20175 see this alternative name in various sources.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20176
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20177 In addition, in each label, each number is followed by a string such
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20178 as @w{@samp{ - }}, which we will call the @code{Y-axis-tic} marker.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20179 This variable is defined with @code{defvar}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20180
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20181 @vindex Y-axis-tic
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20182 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20183 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20184 (defvar Y-axis-tic " - "
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20185 "String that follows number in a Y axis label.")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20186 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20187 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20188
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20189 The length of the Y label is the sum of the length of the Y axis tic
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20190 mark and the length of the number of the top of the graph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20191
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20192 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20193 (length (concat (number-to-string height) Y-axis-tic)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20194 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20195
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20196 This value will be calculated by the @code{print-graph} function in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20197 its varlist as @code{full-Y-label-width} and passed on. (Note that we
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20198 did not think to include this in the varlist when we first proposed it.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20199
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20200 To make a complete vertical axis label, a tic mark is concatenated
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20201 with a number; and the two together may be preceded by one or more
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20202 spaces depending on how long the number is. The label consists of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20203 three parts: the (optional) leading spaces, the number, and the tic
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20204 mark. The function is passed the value of the number for the specific
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20205 row, and the value of the width of the top line, which is calculated
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20206 (just once) by @code{print-graph}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20207
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20208 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20209 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20210 (defun Y-axis-element (number full-Y-label-width)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20211 "Construct a NUMBERed label element.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20212 A numbered element looks like this ` 5 - ',
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20213 and is padded as needed so all line up with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20214 the element for the largest number."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20215 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20216 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20217 (let* ((leading-spaces
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20218 (- full-Y-label-width
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20219 (length
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20220 (concat (number-to-string number)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20221 Y-axis-tic)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20222 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20223 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20224 (concat
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20225 (make-string leading-spaces ? )
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20226 (number-to-string number)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20227 Y-axis-tic)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20228 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20229 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20230
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20231 The @code{Y-axis-element} function concatenates together the leading
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20232 spaces, if any; the number, as a string; and the tic mark.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20233
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20234 To figure out how many leading spaces the label will need, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20235 function subtracts the actual length of the label---the length of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20236 number plus the length of the tic mark---from the desired label width.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20237
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20238 @findex make-string
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20239 Blank spaces are inserted using the @code{make-string} function. This
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20240 function takes two arguments: the first tells it how long the string
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20241 will be and the second is a symbol for the character to insert, in a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20242 special format. The format is a question mark followed by a blank
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20243 space, like this, @samp{? }. @xref{Character Type, , Character Type,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20244 elisp, The GNU Emacs Lisp Reference Manual}, for a description of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20245 syntax for characters. (Of course, you might want to replace the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20246 blank space by some other character @dots{} You know what to do.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20247
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20248 The @code{number-to-string} function is used in the concatenation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20249 expression, to convert the number to a string that is concatenated
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20250 with the leading spaces and the tic mark.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20251
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20252 @node Y-axis-column, print-Y-axis Penultimate, Y Axis Element, print-Y-axis
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20253 @appendixsubsec Create a Y Axis Column
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20254
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20255 The preceding functions provide all the tools needed to construct a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20256 function that generates a list of numbered and blank strings to insert
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20257 as the label for the vertical axis:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20258
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20259 @findex Y-axis-column
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20260 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20261 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20262 (defun Y-axis-column (height width-of-label)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20263 "Construct list of Y axis labels and blank strings.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20264 For HEIGHT of line above base and WIDTH-OF-LABEL."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20265 (let (Y-axis)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20266 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20267 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20268 (while (> height 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20269 (if (zerop (% height Y-axis-label-spacing))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20270 ;; @r{Insert label.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20271 (setq Y-axis
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20272 (cons
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20273 (Y-axis-element height width-of-label)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20274 Y-axis))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20275 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20276 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20277 ;; @r{Else, insert blanks.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20278 (setq Y-axis
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20279 (cons
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20280 (make-string width-of-label ? )
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20281 Y-axis)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20282 (setq height (1- height)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20283 ;; @r{Insert base line.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20284 (setq Y-axis
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20285 (cons (Y-axis-element 1 width-of-label) Y-axis))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20286 (nreverse Y-axis)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20287 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20288 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20289
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20290 In this function, we start with the value of @code{height} and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20291 repetitively subtract one from its value. After each subtraction, we
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20292 test to see whether the value is an integral multiple of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20293 @code{Y-axis-label-spacing}. If it is, we construct a numbered label
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20294 using the @code{Y-axis-element} function; if not, we construct a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20295 blank label using the @code{make-string} function. The base line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20296 consists of the number one followed by a tic mark.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20297
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20298 @need 2000
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20299 @node print-Y-axis Penultimate, , Y-axis-column, print-Y-axis
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20300 @appendixsubsec The Not Quite Final Version of @code{print-Y-axis}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20301
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20302 The list constructed by the @code{Y-axis-column} function is passed to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20303 the @code{print-Y-axis} function, which inserts the list as a column.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20304
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20305 @findex print-Y-axis
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20306 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20307 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20308 (defun print-Y-axis (height full-Y-label-width)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20309 "Insert Y axis using HEIGHT and FULL-Y-LABEL-WIDTH.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20310 Height must be the maximum height of the graph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20311 Full width is the width of the highest label element."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20312 ;; Value of height and full-Y-label-width
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20313 ;; are passed by `print-graph'.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20314 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20315 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20316 (let ((start (point)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20317 (insert-rectangle
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20318 (Y-axis-column height full-Y-label-width))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20319 ;; @r{Place point ready for inserting graph.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20320 (goto-char start)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20321 ;; @r{Move point forward by value of} full-Y-label-width
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20322 (forward-char full-Y-label-width)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20323 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20324 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20325
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20326 The @code{print-Y-axis} uses the @code{insert-rectangle} function to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20327 insert the Y axis labels created by the @code{Y-axis-column} function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20328 In addition, it places point at the correct position for printing the body of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20329 the graph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20330
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20331 You can test @code{print-Y-axis}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20332
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20333 @enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20334 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20335 Install
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20336
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20337 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20338 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20339 Y-axis-label-spacing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20340 Y-axis-tic
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20341 Y-axis-element
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20342 Y-axis-column
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20343 print-Y-axis
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20344 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20345 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20346
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20347 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20348 Copy the following expression:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20349
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20350 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20351 (print-Y-axis 12 5)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20352 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20353
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20354 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20355 Switch to the @file{*scratch*} buffer and place the cursor where you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20356 want the axis labels to start.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20357
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20358 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20359 Type @kbd{M-:} (@code{eval-expression}).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20360
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20361 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20362 Yank the @code{graph-body-print} expression into the minibuffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20363 with @kbd{C-y} (@code{yank)}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20364
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20365 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20366 Press @key{RET} to evaluate the expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20367 @end enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20368
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20369 Emacs will print labels vertically, the top one being @w{@samp{10 -@w{
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20370 }}}. (The @code{print-graph} function will pass the value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20371 @code{height-of-top-line}, which in this case will end up as 15,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20372 thereby getting rid of what might appear as a bug.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20373
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20374 @need 2000
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20375 @node print-X-axis, Print Whole Graph, print-Y-axis, Full Graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20376 @appendixsec The @code{print-X-axis} Function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20377 @cindex Axis, print horizontal
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20378 @cindex X axis printing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20379 @cindex Print horizontal axis
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20380 @cindex Horizontal axis printing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20381
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20382 X axis labels are much like Y axis labels, except that the ticks are on a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20383 line above the numbers. Labels should look like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20384
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20385 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20386 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20387 | | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20388 1 5 10 15
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20389 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20390 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20391
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20392 The first tic is under the first column of the graph and is preceded by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20393 several blank spaces. These spaces provide room in rows above for the Y
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20394 axis labels. The second, third, fourth, and subsequent ticks are all
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20395 spaced equally, according to the value of @code{X-axis-label-spacing}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20396
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20397 The second row of the X axis consists of numbers, preceded by several
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20398 blank spaces and also separated according to the value of the variable
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20399 @code{X-axis-label-spacing}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20400
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20401 The value of the variable @code{X-axis-label-spacing} should itself be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20402 measured in units of @code{symbol-width}, since you may want to change
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20403 the width of the symbols that you are using to print the body of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20404 graph without changing the ways the graph is labelled.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20405
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20406 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20407 * Similarities differences:: Much like @code{print-Y-axis}, but not exactly.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20408 * X Axis Tic Marks:: Create tic marks for the horizontal axis.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20409 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20410
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20411 @node Similarities differences, X Axis Tic Marks, print-X-axis, print-X-axis
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20412 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20413 @unnumberedsubsec Similarities and differences
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20414 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20415
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20416 The @code{print-X-axis} function is constructed in more or less the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20417 same fashion as the @code{print-Y-axis} function except that it has
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20418 two lines: the line of tic marks and the numbers. We will write a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20419 separate function to print each line and then combine them within the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20420 @code{print-X-axis} function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20421
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20422 This is a three step process:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20423
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20424 @enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20425 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20426 Write a function to print the X axis tic marks, @code{print-X-axis-tic-line}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20427
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20428 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20429 Write a function to print the X numbers, @code{print-X-axis-numbered-line}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20430
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20431 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20432 Write a function to print both lines, the @code{print-X-axis} function,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20433 using @code{print-X-axis-tic-line} and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20434 @code{print-X-axis-numbered-line}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20435 @end enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20436
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20437 @node X Axis Tic Marks, , Similarities differences, print-X-axis
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20438 @appendixsubsec X Axis Tic Marks
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20439
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20440 The first function should print the X axis tic marks. We must specify
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20441 the tic marks themselves and their spacing:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20442
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20443 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20444 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20445 (defvar X-axis-label-spacing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20446 (if (boundp 'graph-blank)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20447 (* 5 (length graph-blank)) 5)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20448 "Number of units from one X axis label to next.")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20449 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20450 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20451
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20452 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20453 (Note that the value of @code{graph-blank} is set by another
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20454 @code{defvar}. The @code{boundp} predicate checks whether it has
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20455 already been set; @code{boundp} returns @code{nil} if it has not. If
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20456 @code{graph-blank} were unbound and we did not use this conditional
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20457 construction, in a recent GNU Emacs, we would enter the debugger and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20458 see an error message saying @samp{@w{Debugger entered--Lisp error:}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20459 @w{(void-variable graph-blank)}}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20460
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20461 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20462 Here is the @code{defvar} for @code{X-axis-tic-symbol}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20463
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20464 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20465 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20466 (defvar X-axis-tic-symbol "|"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20467 "String to insert to point to a column in X axis.")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20468 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20469 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20470
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20471 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20472 The goal is to make a line that looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20473
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20474 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20475 | | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20476 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20477
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20478 The first tic is indented so that it is under the first column, which is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20479 indented to provide space for the Y axis labels.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20480
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20481 A tic element consists of the blank spaces that stretch from one tic to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20482 the next plus a tic symbol. The number of blanks is determined by the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20483 width of the tic symbol and the @code{X-axis-label-spacing}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20484
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20485 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20486 The code looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20487
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20488 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20489 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20490 ;;; X-axis-tic-element
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20491 @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20492 (concat
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20493 (make-string
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20494 ;; @r{Make a string of blanks.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20495 (- (* symbol-width X-axis-label-spacing)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20496 (length X-axis-tic-symbol))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20497 ? )
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20498 ;; @r{Concatenate blanks with tic symbol.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20499 X-axis-tic-symbol)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20500 @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20501 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20502 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20503
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20504 Next, we determine how many blanks are needed to indent the first tic
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20505 mark to the first column of the graph. This uses the value of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20506 @code{full-Y-label-width} passed it by the @code{print-graph} function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20507
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20508 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20509 The code to make @code{X-axis-leading-spaces}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20510 looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20511
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20512 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20513 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20514 ;; X-axis-leading-spaces
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20515 @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20516 (make-string full-Y-label-width ? )
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20517 @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20518 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20519 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20520
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20521 We also need to determine the length of the horizontal axis, which is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20522 the length of the numbers list, and the number of ticks in the horizontal
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20523 axis:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20524
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20525 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20526 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20527 ;; X-length
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20528 @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20529 (length numbers-list)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20530 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20531
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20532 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20533 ;; tic-width
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20534 @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20535 (* symbol-width X-axis-label-spacing)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20536 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20537
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20538 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20539 ;; number-of-X-ticks
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20540 (if (zerop (% (X-length tic-width)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20541 (/ (X-length tic-width))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20542 (1+ (/ (X-length tic-width))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20543 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20544 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20545
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20546 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20547 All this leads us directly to the function for printing the X axis tic line:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20548
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20549 @findex print-X-axis-tic-line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20550 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20551 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20552 (defun print-X-axis-tic-line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20553 (number-of-X-tics X-axis-leading-spaces X-axis-tic-element)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20554 "Print ticks for X axis."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20555 (insert X-axis-leading-spaces)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20556 (insert X-axis-tic-symbol) ; @r{Under first column.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20557 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20558 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20559 ;; @r{Insert second tic in the right spot.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20560 (insert (concat
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20561 (make-string
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20562 (- (* symbol-width X-axis-label-spacing)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20563 ;; @r{Insert white space up to second tic symbol.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20564 (* 2 (length X-axis-tic-symbol)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20565 ? )
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20566 X-axis-tic-symbol))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20567 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20568 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20569 ;; @r{Insert remaining ticks.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20570 (while (> number-of-X-tics 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20571 (insert X-axis-tic-element)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20572 (setq number-of-X-tics (1- number-of-X-tics))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20573 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20574 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20575
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20576 The line of numbers is equally straightforward:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20577
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20578 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20579 First, we create a numbered element with blank spaces before each number:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20580
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20581 @findex X-axis-element
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20582 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20583 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20584 (defun X-axis-element (number)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20585 "Construct a numbered X axis element."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20586 (let ((leading-spaces
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20587 (- (* symbol-width X-axis-label-spacing)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20588 (length (number-to-string number)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20589 (concat (make-string leading-spaces ? )
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20590 (number-to-string number))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20591 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20592 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20593
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20594 Next, we create the function to print the numbered line, starting with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20595 the number ``1'' under the first column:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20596
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20597 @findex print-X-axis-numbered-line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20598 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20599 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20600 (defun print-X-axis-numbered-line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20601 (number-of-X-tics X-axis-leading-spaces)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20602 "Print line of X-axis numbers"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20603 (let ((number X-axis-label-spacing))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20604 (insert X-axis-leading-spaces)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20605 (insert "1")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20606 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20607 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20608 (insert (concat
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20609 (make-string
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20610 ;; @r{Insert white space up to next number.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20611 (- (* symbol-width X-axis-label-spacing) 2)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20612 ? )
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20613 (number-to-string number)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20614 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20615 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20616 ;; @r{Insert remaining numbers.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20617 (setq number (+ number X-axis-label-spacing))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20618 (while (> number-of-X-tics 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20619 (insert (X-axis-element number))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20620 (setq number (+ number X-axis-label-spacing))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20621 (setq number-of-X-tics (1- number-of-X-tics)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20622 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20623 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20624
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20625 Finally, we need to write the @code{print-X-axis} that uses
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20626 @code{print-X-axis-tic-line} and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20627 @code{print-X-axis-numbered-line}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20628
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20629 The function must determine the local values of the variables used by both
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20630 @code{print-X-axis-tic-line} and @code{print-X-axis-numbered-line}, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20631 then it must call them. Also, it must print the carriage return that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20632 separates the two lines.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20633
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20634 The function consists of a varlist that specifies five local variables,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20635 and calls to each of the two line printing functions:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20636
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20637 @findex print-X-axis
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20638 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20639 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20640 (defun print-X-axis (numbers-list)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20641 "Print X axis labels to length of NUMBERS-LIST."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20642 (let* ((leading-spaces
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20643 (make-string full-Y-label-width ? ))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20644 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20645 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20646 ;; symbol-width @r{is provided by} graph-body-print
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20647 (tic-width (* symbol-width X-axis-label-spacing))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20648 (X-length (length numbers-list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20649 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20650 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20651 (X-tic
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20652 (concat
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20653 (make-string
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20654 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20655 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20656 ;; @r{Make a string of blanks.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20657 (- (* symbol-width X-axis-label-spacing)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20658 (length X-axis-tic-symbol))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20659 ? )
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20660 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20661 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20662 ;; @r{Concatenate blanks with tic symbol.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20663 X-axis-tic-symbol))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20664 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20665 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20666 (tic-number
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20667 (if (zerop (% X-length tic-width))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20668 (/ X-length tic-width)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20669 (1+ (/ X-length tic-width)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20670 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20671 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20672 (print-X-axis-tic-line tic-number leading-spaces X-tic)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20673 (insert "\n")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20674 (print-X-axis-numbered-line tic-number leading-spaces)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20675 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20676 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20677
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20678 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20679 You can test @code{print-X-axis}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20680
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20681 @enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20682 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20683 Install @code{X-axis-tic-symbol}, @code{X-axis-label-spacing},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20684 @code{print-X-axis-tic-line}, as well as @code{X-axis-element},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20685 @code{print-X-axis-numbered-line}, and @code{print-X-axis}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20686
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20687 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20688 Copy the following expression:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20689
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20690 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20691 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20692 (progn
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20693 (let ((full-Y-label-width 5)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20694 (symbol-width 1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20695 (print-X-axis
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20696 '(1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20697 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20698 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20699
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20700 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20701 Switch to the @file{*scratch*} buffer and place the cursor where you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20702 want the axis labels to start.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20703
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20704 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20705 Type @kbd{M-:} (@code{eval-expression}).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20706
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20707 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20708 Yank the test expression into the minibuffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20709 with @kbd{C-y} (@code{yank)}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20710
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20711 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20712 Press @key{RET} to evaluate the expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20713 @end enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20714
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20715 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20716 Emacs will print the horizontal axis like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20717 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20718
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20719 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20720 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20721 | | | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20722 1 5 10 15 20
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20723 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20724 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20725
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20726 @node Print Whole Graph, , print-X-axis, Full Graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20727 @appendixsec Printing the Whole Graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20728 @cindex Printing the whole graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20729 @cindex Whole graph printing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20730 @cindex Graph, printing all
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20731
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20732 Now we are nearly ready to print the whole graph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20733
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20734 The function to print the graph with the proper labels follows the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20735 outline we created earlier (@pxref{Full Graph, , A Graph with Labelled
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20736 Axes}), but with additions.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20737
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20738 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20739 Here is the outline:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20740
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20741 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20742 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20743 (defun print-graph (numbers-list)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20744 "@var{documentation}@dots{}"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20745 (let ((height @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20746 @dots{}))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20747 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20748 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20749 (print-Y-axis height @dots{} )
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20750 (graph-body-print numbers-list)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20751 (print-X-axis @dots{} )))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20752 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20753 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20754
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20755 @menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20756 * The final version:: A few changes.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20757 * Test print-graph:: Run a short test.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20758 * Graphing words in defuns:: Executing the final code.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20759 * lambda:: How to write an anonymous function.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20760 * mapcar:: Apply a function to elements of a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20761 * Another Bug:: Yet another bug @dots{} most insidious.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20762 * Final printed graph:: The graph itself!
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20763 @end menu
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20764
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20765 @node The final version, Test print-graph, Print Whole Graph, Print Whole Graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20766 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20767 @unnumberedsubsec Changes for the Final Version
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20768 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20769
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20770 The final version is different from what we planned in two ways:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20771 first, it contains additional values calculated once in the varlist;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20772 second, it carries an option to specify the labels' increment per row.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20773 This latter feature turns out to be essential; otherwise, a graph may
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20774 have more rows than fit on a display or on a sheet of paper.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20775
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20776 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20777 This new feature requires a change to the @code{Y-axis-column}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20778 function, to add @code{vertical-step} to it. The function looks like
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20779 this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20780
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20781 @findex Y-axis-column @r{Final version.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20782 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20783 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20784 ;;; @r{Final version.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20785 (defun Y-axis-column
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20786 (height width-of-label &optional vertical-step)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20787 "Construct list of labels for Y axis.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20788 HEIGHT is maximum height of graph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20789 WIDTH-OF-LABEL is maximum width of label.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20790 VERTICAL-STEP, an option, is a positive integer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20791 that specifies how much a Y axis label increments
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20792 for each line. For example, a step of 5 means
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20793 that each line is five units of the graph."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20794 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20795 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20796 (let (Y-axis
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20797 (number-per-line (or vertical-step 1)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20798 (while (> height 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20799 (if (zerop (% height Y-axis-label-spacing))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20800 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20801 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20802 ;; @r{Insert label.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20803 (setq Y-axis
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20804 (cons
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20805 (Y-axis-element
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20806 (* height number-per-line)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20807 width-of-label)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20808 Y-axis))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20809 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20810 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20811 ;; @r{Else, insert blanks.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20812 (setq Y-axis
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20813 (cons
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20814 (make-string width-of-label ? )
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20815 Y-axis)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20816 (setq height (1- height)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20817 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20818 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20819 ;; @r{Insert base line.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20820 (setq Y-axis (cons (Y-axis-element
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20821 (or vertical-step 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20822 width-of-label)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20823 Y-axis))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20824 (nreverse Y-axis)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20825 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20826 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20827
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20828 The values for the maximum height of graph and the width of a symbol
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20829 are computed by @code{print-graph} in its @code{let} expression; so
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20830 @code{graph-body-print} must be changed to accept them.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20831
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20832 @findex graph-body-print @r{Final version.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20833 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20834 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20835 ;;; @r{Final version.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20836 (defun graph-body-print (numbers-list height symbol-width)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20837 "Print a bar graph of the NUMBERS-LIST.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20838 The numbers-list consists of the Y-axis values.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20839 HEIGHT is maximum height of graph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20840 SYMBOL-WIDTH is number of each column."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20841 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20842 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20843 (let (from-position)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20844 (while numbers-list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20845 (setq from-position (point))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20846 (insert-rectangle
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20847 (column-of-graph height (car numbers-list)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20848 (goto-char from-position)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20849 (forward-char symbol-width)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20850 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20851 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20852 ;; @r{Draw graph column by column.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20853 (sit-for 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20854 (setq numbers-list (cdr numbers-list)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20855 ;; @r{Place point for X axis labels.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20856 (forward-line height)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20857 (insert "\n")))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20858 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20859 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20860
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20861 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20862 Finally, the code for the @code{print-graph} function:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20863
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20864 @findex print-graph @r{Final version.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20865 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20866 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20867 ;;; @r{Final version.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20868 (defun print-graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20869 (numbers-list &optional vertical-step)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20870 "Print labelled bar graph of the NUMBERS-LIST.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20871 The numbers-list consists of the Y-axis values.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20872 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20873
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20874 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20875 Optionally, VERTICAL-STEP, a positive integer,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20876 specifies how much a Y axis label increments for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20877 each line. For example, a step of 5 means that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20878 each row is five units."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20879 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20880 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20881 (let* ((symbol-width (length graph-blank))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20882 ;; @code{height} @r{is both the largest number}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20883 ;; @r{and the number with the most digits.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20884 (height (apply 'max numbers-list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20885 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20886 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20887 (height-of-top-line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20888 (if (zerop (% height Y-axis-label-spacing))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20889 height
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20890 ;; @r{else}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20891 (* (1+ (/ height Y-axis-label-spacing))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20892 Y-axis-label-spacing)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20893 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20894 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20895 (vertical-step (or vertical-step 1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20896 (full-Y-label-width
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20897 (length
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20898 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20899 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20900 (concat
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20901 (number-to-string
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20902 (* height-of-top-line vertical-step))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20903 Y-axis-tic))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20904 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20905
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20906 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20907 (print-Y-axis
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20908 height-of-top-line full-Y-label-width vertical-step)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20909 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20910 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20911 (graph-body-print
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20912 numbers-list height-of-top-line symbol-width)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20913 (print-X-axis numbers-list)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20914 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20915 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20916
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20917 @node Test print-graph, Graphing words in defuns, The final version, Print Whole Graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20918 @appendixsubsec Testing @code{print-graph}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20919
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20920 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20921 We can test the @code{print-graph} function with a short list of numbers:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20922
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20923 @enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20924 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20925 Install the final versions of @code{Y-axis-column},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20926 @code{graph-body-print}, and @code{print-graph} (in addition to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20927 rest of the code.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20928
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20929 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20930 Copy the following expression:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20931
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20932 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20933 (print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20934 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20935
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20936 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20937 Switch to the @file{*scratch*} buffer and place the cursor where you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20938 want the axis labels to start.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20939
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20940 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20941 Type @kbd{M-:} (@code{eval-expression}).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20942
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20943 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20944 Yank the test expression into the minibuffer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20945 with @kbd{C-y} (@code{yank)}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20946
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20947 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20948 Press @key{RET} to evaluate the expression.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20949 @end enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20950
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20951 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20952 Emacs will print a graph that looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20953
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20954 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20955 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20956 10 -
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20957
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20958
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20959 *
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20960 ** *
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20961 5 - **** *
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20962 **** ***
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20963 * *********
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20964 ************
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20965 1 - *************
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20966
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20967 | | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20968 1 5 10 15
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20969 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20970 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20971
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20972 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20973 On the other hand, if you pass @code{print-graph} a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20974 @code{vertical-step} value of 2, by evaluating this expression:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20975
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20976 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20977 (print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1) 2)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20978 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20979
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20980 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20981 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20982 The graph looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20983
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20984 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20985 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20986 20 -
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20987
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20988
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20989 *
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20990 ** *
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20991 10 - **** *
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20992 **** ***
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20993 * *********
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20994 ************
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20995 2 - *************
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20996
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20997 | | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20998 1 5 10 15
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20999 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21000 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21001
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21002 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21003 (A question: is the `2' on the bottom of the vertical axis a bug or a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21004 feature? If you think it is a bug, and should be a `1' instead, (or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21005 even a `0'), you can modify the sources.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21006
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21007 @node Graphing words in defuns, lambda, Test print-graph, Print Whole Graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21008 @appendixsubsec Graphing Numbers of Words and Symbols
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21009
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21010 Now for the graph for which all this code was written: a graph that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21011 shows how many function definitions contain fewer than 10 words and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21012 symbols, how many contain between 10 and 19 words and symbols, how
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21013 many contain between 20 and 29 words and symbols, and so on.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21014
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21015 This is a multi-step process. First make sure you have loaded all the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21016 requisite code.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21017
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21018 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21019 It is a good idea to reset the value of @code{top-of-ranges} in case
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21020 you have set it to some different value. You can evaluate the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21021 following:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21022
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21023 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21024 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21025 (setq top-of-ranges
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21026 '(10 20 30 40 50
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21027 60 70 80 90 100
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21028 110 120 130 140 150
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21029 160 170 180 190 200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21030 210 220 230 240 250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21031 260 270 280 290 300)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21032 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21033 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21034
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21035 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21036 Next create a list of the number of words and symbols in each range.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21037
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21038 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21039 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21040 Evaluate the following:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21041
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21042 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21043 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21044 (setq list-for-graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21045 (defuns-per-range
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21046 (sort
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21047 (recursive-lengths-list-many-files
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21048 (directory-files "/usr/local/emacs/lisp"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21049 t ".+el$"))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21050 '<)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21051 top-of-ranges))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21052 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21053 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21054
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21055 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21056 On my old machine, this took about an hour. It looked though 303 Lisp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21057 files in my copy of Emacs version 19.23. After all that computing,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21058 the @code{list-for-graph} had this value:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21059
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21060 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21061 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21062 (537 1027 955 785 594 483 349 292 224 199 166 120 116 99
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21063 90 80 67 48 52 45 41 33 28 26 25 20 12 28 11 13 220)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21064 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21065 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21066
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21067 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21068 This means that my copy of Emacs had 537 function definitions with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21069 fewer than 10 words or symbols in them, 1,027 function definitions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21070 with 10 to 19 words or symbols in them, 955 function definitions with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21071 20 to 29 words or symbols in them, and so on.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21072
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21073 Clearly, just by looking at this list we can see that most function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21074 definitions contain ten to thirty words and symbols.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21075
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21076 Now for printing. We do @emph{not} want to print a graph that is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21077 1,030 lines high @dots{} Instead, we should print a graph that is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21078 fewer than twenty-five lines high. A graph that height can be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21079 displayed on almost any monitor, and easily printed on a sheet of paper.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21080
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21081 This means that each value in @code{list-for-graph} must be reduced to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21082 one-fiftieth its present value.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21083
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21084 Here is a short function to do just that, using two functions we have
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21085 not yet seen, @code{mapcar} and @code{lambda}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21086
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21087 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21088 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21089 (defun one-fiftieth (full-range)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21090 "Return list, each number one-fiftieth of previous."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21091 (mapcar '(lambda (arg) (/ arg 50)) full-range))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21092 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21093 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21094
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21095 @node lambda, mapcar, Graphing words in defuns, Print Whole Graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21096 @appendixsubsec A @code{lambda} Expression: Useful Anonymity
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21097 @cindex Anonymous function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21098 @findex lambda
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21099
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21100 @code{lambda} is the symbol for an anonymous function, a function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21101 without a name. Every time you use an anonymous function, you need to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21102 include its whole body.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21103
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21104 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21105 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21106 Thus,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21107
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21108 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21109 (lambda (arg) (/ arg 50))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21110 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21111
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21112 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21113 is a function definition that says `return the value resulting from
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21114 dividing whatever is passed to me as @code{arg} by 50'.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21115
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21116 @need 1200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21117 Earlier, for example, we had a function @code{multiply-by-seven}; it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21118 multiplied its argument by 7. This function is similar, except it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21119 divides its argument by 50; and, it has no name. The anonymous
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21120 equivalent of @code{multiply-by-seven} is:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21121
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21122 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21123 (lambda (number) (* 7 number))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21124 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21125
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21126 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21127 (@xref{defun, , The @code{defun} Special Form}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21128
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21129 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21130 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21131 If we want to multiply 3 by 7, we can write:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21132
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21133 @c !!! Clear print-postscript-figures if the computer formatting this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21134 @c document is too small and cannot handle all the diagrams and figures.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21135 @c clear print-postscript-figures
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21136 @c set print-postscript-figures
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21137 @c lambda example diagram #1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21138 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21139 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21140 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21141 (multiply-by-seven 3)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21142 \_______________/ ^
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21143 | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21144 function argument
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21145 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21146 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21147 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21148 @ifset print-postscript-figures
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21149 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21150 @tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21151 @center @image{lambda-1}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21152 %%%% old method of including an image
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21153 % \input /usr/local/lib/tex/inputs/psfig.tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21154 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-1.eps}}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21155 % \catcode`\@=0 %
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21156 @end tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21157 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21158 @end ifset
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21159 @ifclear print-postscript-figures
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21160 @iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21161 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21162 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21163 (multiply-by-seven 3)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21164 \_______________/ ^
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21165 | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21166 function argument
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21167 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21168 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21169 @end iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21170 @end ifclear
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21171
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21172 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21173 This expression returns 21.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21174
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21175 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21176 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21177 Similarly, we can write:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21178
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21179 @c lambda example diagram #2
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21180 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21181 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21182 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21183 ((lambda (number) (* 7 number)) 3)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21184 \____________________________/ ^
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21185 | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21186 anonymous function argument
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21187 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21188 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21189 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21190 @ifset print-postscript-figures
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21191 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21192 @tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21193 @center @image{lambda-2}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21194 %%%% old method of including an image
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21195 % \input /usr/local/lib/tex/inputs/psfig.tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21196 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-2.eps}}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21197 % \catcode`\@=0 %
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21198 @end tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21199 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21200 @end ifset
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21201 @ifclear print-postscript-figures
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21202 @iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21203 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21204 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21205 ((lambda (number) (* 7 number)) 3)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21206 \____________________________/ ^
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21207 | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21208 anonymous function argument
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21209 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21210 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21211 @end iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21212 @end ifclear
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21213
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21214 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21215 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21216 If we want to divide 100 by 50, we can write:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21217
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21218 @c lambda example diagram #3
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21219 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21220 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21221 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21222 ((lambda (arg) (/ arg 50)) 100)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21223 \______________________/ \_/
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21224 | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21225 anonymous function argument
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21226 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21227 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21228 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21229 @ifset print-postscript-figures
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21230 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21231 @tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21232 @center @image{lambda-3}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21233 %%%% old method of including an image
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21234 % \input /usr/local/lib/tex/inputs/psfig.tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21235 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-3.eps}}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21236 % \catcode`\@=0 %
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21237 @end tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21238 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21239 @end ifset
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21240 @ifclear print-postscript-figures
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21241 @iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21242 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21243 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21244 ((lambda (arg) (/ arg 50)) 100)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21245 \______________________/ \_/
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21246 | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21247 anonymous function argument
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21248 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21249 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21250 @end iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21251 @end ifclear
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21252
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21253 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21254 This expression returns 2. The 100 is passed to the function, which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21255 divides that number by 50.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21256
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21257 @xref{Lambda Expressions, , Lambda Expressions, elisp, The GNU Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21258 Lisp Reference Manual}, for more about @code{lambda}. Lisp and lambda
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21259 expressions derive from the Lambda Calculus.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21260
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21261 @node mapcar, Another Bug, lambda, Print Whole Graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21262 @appendixsubsec The @code{mapcar} Function
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21263 @findex mapcar
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21264
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21265 @code{mapcar} is a function that calls its first argument with each
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21266 element of its second argument, in turn. The second argument must be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21267 a sequence.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21268
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21269 The @samp{map} part of the name comes from the mathematical phrase,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21270 `mapping over a domain', meaning to apply a function to each of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21271 elements in a domain. The mathematical phrase is based on the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21272 metaphor of a surveyor walking, one step at a time, over an area he is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21273 mapping. And @samp{car}, of course, comes from the Lisp notion of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21274 first of a list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21275
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21276 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21277 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21278 For example,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21279
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21280 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21281 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21282 (mapcar '1+ '(2 4 6))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21283 @result{} (3 5 7)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21284 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21285 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21286
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21287 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21288 The function @code{1+} which adds one to its argument, is executed on
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21289 @emph{each} element of the list, and a new list is returned.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21290
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21291 Contrast this with @code{apply}, which applies its first argument to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21292 all the remaining.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21293 (@xref{Readying a Graph, , Readying a Graph}, for a explanation of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21294 @code{apply}.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21295
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21296 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21297 In the definition of @code{one-fiftieth}, the first argument is the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21298 anonymous function:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21299
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21300 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21301 (lambda (arg) (/ arg 50))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21302 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21303
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21304 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21305 and the second argument is @code{full-range}, which will be bound to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21306 @code{list-for-graph}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21307
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21308 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21309 The whole expression looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21310
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21311 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21312 (mapcar '(lambda (arg) (/ arg 50)) full-range))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21313 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21314
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21315 @xref{Mapping Functions, , Mapping Functions, elisp, The GNU Emacs
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21316 Lisp Reference Manual}, for more about @code{mapcar}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21317
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21318 Using the @code{one-fiftieth} function, we can generate a list in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21319 which each element is one-fiftieth the size of the corresponding
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21320 element in @code{list-for-graph}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21321
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21322 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21323 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21324 (setq fiftieth-list-for-graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21325 (one-fiftieth list-for-graph))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21326 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21327 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21328
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21329 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21330 The resulting list looks like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21331
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21332 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21333 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21334 (10 20 19 15 11 9 6 5 4 3 3 2 2
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21335 1 1 1 1 0 1 0 0 0 0 0 0 0 0 0 0 0 4)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21336 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21337 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21338
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21339 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21340 This, we are almost ready to print! (We also notice the loss of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21341 information: many of the higher ranges are 0, meaning that fewer than
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21342 50 defuns had that many words or symbols---but not necessarily meaning
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21343 that none had that many words or symbols.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21344
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21345 @node Another Bug, Final printed graph, mapcar, Print Whole Graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21346 @appendixsubsec Another Bug @dots{} Most Insidious
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21347 @cindex Bug, most insidious type
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21348 @cindex Insidious type of bug
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21349
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21350 I said `almost ready to print'! Of course, there is a bug in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21351 @code{print-graph} function @dots{} It has a @code{vertical-step}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21352 option, but not a @code{horizontal-step} option. The
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21353 @code{top-of-range} scale goes from 10 to 300 by tens. But the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21354 @code{print-graph} function will print only by ones.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21355
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21356 This is a classic example of what some consider the most insidious
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21357 type of bug, the bug of omission. This is not the kind of bug you can
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21358 find by studying the code, for it is not in the code; it is an omitted
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21359 feature. Your best actions are to try your program early and often;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21360 and try to arrange, as much as you can, to write code that is easy to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21361 understand and easy to change. Try to be aware, whenever you can,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21362 that whatever you have written, @emph{will} be rewritten, if not soon,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21363 eventually. A hard maxim to follow.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21364
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21365 It is the @code{print-X-axis-numbered-line} function that needs the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21366 work; and then the @code{print-X-axis} and the @code{print-graph}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21367 functions need to be adapted. Not much needs to be done; there is one
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21368 nicety: the numbers ought to line up under the tic marks. This takes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21369 a little thought.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21370
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21371 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21372 Here is the corrected @code{print-X-axis-numbered-line}:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21373
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21374 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21375 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21376 (defun print-X-axis-numbered-line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21377 (number-of-X-tics X-axis-leading-spaces
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21378 &optional horizontal-step)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21379 "Print line of X-axis numbers"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21380 (let ((number X-axis-label-spacing)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21381 (horizontal-step (or horizontal-step 1)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21382 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21383 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21384 (insert X-axis-leading-spaces)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21385 ;; @r{Delete extra leading spaces.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21386 (delete-char
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21387 (- (1-
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21388 (length (number-to-string horizontal-step)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21389 (insert (concat
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21390 (make-string
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21391 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21392 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21393 ;; @r{Insert white space.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21394 (- (* symbol-width
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21395 X-axis-label-spacing)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21396 (1-
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21397 (length
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21398 (number-to-string horizontal-step)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21399 2)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21400 ? )
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21401 (number-to-string
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21402 (* number horizontal-step))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21403 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21404 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21405 ;; @r{Insert remaining numbers.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21406 (setq number (+ number X-axis-label-spacing))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21407 (while (> number-of-X-tics 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21408 (insert (X-axis-element
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21409 (* number horizontal-step)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21410 (setq number (+ number X-axis-label-spacing))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21411 (setq number-of-X-tics (1- number-of-X-tics)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21412 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21413 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21414
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21415 @need 1500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21416 If you are reading this in Info, you can see the new versions of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21417 @code{print-X-axis} @code{print-graph} and evaluate them. If you are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21418 reading this in a printed book, you can see the changed lines here
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21419 (the full text is too much to print).
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21420
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21421 @iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21422 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21423 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21424 (defun print-X-axis (numbers-list horizontal-step)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21425 @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21426 (print-X-axis-numbered-line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21427 tic-number leading-spaces horizontal-step))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21428 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21429 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21430
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21431 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21432 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21433 (defun print-graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21434 (numbers-list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21435 &optional vertical-step horizontal-step)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21436 @dots{}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21437 (print-X-axis numbers-list horizontal-step))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21438 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21439 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21440 @end iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21441
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21442 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21443 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21444 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21445 (defun print-X-axis (numbers-list horizontal-step)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21446 "Print X axis labels to length of NUMBERS-LIST.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21447 Optionally, HORIZONTAL-STEP, a positive integer,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21448 specifies how much an X axis label increments for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21449 each column."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21450 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21451 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21452 ;; Value of symbol-width and full-Y-label-width
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21453 ;; are passed by `print-graph'.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21454 (let* ((leading-spaces
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21455 (make-string full-Y-label-width ? ))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21456 ;; symbol-width @r{is provided by} graph-body-print
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21457 (tic-width (* symbol-width X-axis-label-spacing))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21458 (X-length (length numbers-list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21459 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21460 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21461 (X-tic
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21462 (concat
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21463 (make-string
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21464 ;; @r{Make a string of blanks.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21465 (- (* symbol-width X-axis-label-spacing)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21466 (length X-axis-tic-symbol))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21467 ? )
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21468 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21469 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21470 ;; @r{Concatenate blanks with tic symbol.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21471 X-axis-tic-symbol))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21472 (tic-number
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21473 (if (zerop (% X-length tic-width))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21474 (/ X-length tic-width)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21475 (1+ (/ X-length tic-width)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21476 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21477
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21478 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21479 (print-X-axis-tic-line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21480 tic-number leading-spaces X-tic)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21481 (insert "\n")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21482 (print-X-axis-numbered-line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21483 tic-number leading-spaces horizontal-step)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21484 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21485 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21486
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21487 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21488 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21489 (defun print-graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21490 (numbers-list &optional vertical-step horizontal-step)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21491 "Print labelled bar graph of the NUMBERS-LIST.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21492 The numbers-list consists of the Y-axis values.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21493 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21494
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21495 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21496 Optionally, VERTICAL-STEP, a positive integer,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21497 specifies how much a Y axis label increments for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21498 each line. For example, a step of 5 means that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21499 each row is five units.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21500 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21501
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21502 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21503 Optionally, HORIZONTAL-STEP, a positive integer,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21504 specifies how much an X axis label increments for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21505 each column."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21506 (let* ((symbol-width (length graph-blank))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21507 ;; @code{height} @r{is both the largest number}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21508 ;; @r{and the number with the most digits.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21509 (height (apply 'max numbers-list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21510 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21511 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21512 (height-of-top-line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21513 (if (zerop (% height Y-axis-label-spacing))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21514 height
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21515 ;; @r{else}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21516 (* (1+ (/ height Y-axis-label-spacing))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21517 Y-axis-label-spacing)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21518 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21519 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21520 (vertical-step (or vertical-step 1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21521 (full-Y-label-width
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21522 (length
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21523 (concat
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21524 (number-to-string
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21525 (* height-of-top-line vertical-step))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21526 Y-axis-tic))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21527 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21528 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21529 (print-Y-axis
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21530 height-of-top-line full-Y-label-width vertical-step)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21531 (graph-body-print
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21532 numbers-list height-of-top-line symbol-width)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21533 (print-X-axis numbers-list horizontal-step)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21534 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21535 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21536 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21537
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21538 @c qqq
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21539 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21540 Graphing Definitions Re-listed
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21541
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21542 @need 1250
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21543 Here are all the graphing definitions in their final form:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21544
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21545 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21546 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21547 (defvar top-of-ranges
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21548 '(10 20 30 40 50
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21549 60 70 80 90 100
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21550 110 120 130 140 150
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21551 160 170 180 190 200
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21552 210 220 230 240 250)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21553 "List specifying ranges for `defuns-per-range'.")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21554 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21555
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21556 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21557 (defvar graph-symbol "*"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21558 "String used as symbol in graph, usually an asterisk.")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21559 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21560
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21561 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21562 (defvar graph-blank " "
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21563 "String used as blank in graph, usually a blank space.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21564 graph-blank must be the same number of columns wide
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21565 as graph-symbol.")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21566 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21567
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21568 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21569 (defvar Y-axis-tic " - "
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21570 "String that follows number in a Y axis label.")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21571 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21572
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21573 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21574 (defvar Y-axis-label-spacing 5
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21575 "Number of lines from one Y axis label to next.")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21576 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21577
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21578 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21579 (defvar X-axis-tic-symbol "|"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21580 "String to insert to point to a column in X axis.")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21581 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21582
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21583 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21584 (defvar X-axis-label-spacing
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21585 (if (boundp 'graph-blank)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21586 (* 5 (length graph-blank)) 5)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21587 "Number of units from one X axis label to next.")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21588 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21589 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21590
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21591 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21592 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21593 (defun count-words-in-defun ()
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21594 "Return the number of words and symbols in a defun."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21595 (beginning-of-defun)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21596 (let ((count 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21597 (end (save-excursion (end-of-defun) (point))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21598 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21599
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21600 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21601 (while
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21602 (and (< (point) end)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21603 (re-search-forward
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21604 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21605 end t))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21606 (setq count (1+ count)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21607 count))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21608 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21609 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21610
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21611 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21612 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21613 (defun lengths-list-file (filename)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21614 "Return list of definitions' lengths within FILE.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21615 The returned list is a list of numbers.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21616 Each number is the number of words or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21617 symbols in one function definition."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21618 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21619
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21620 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21621 (message "Working on `%s' ... " filename)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21622 (save-excursion
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21623 (let ((buffer (find-file-noselect filename))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21624 (lengths-list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21625 (set-buffer buffer)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21626 (setq buffer-read-only t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21627 (widen)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21628 (goto-char (point-min))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21629 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21630
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21631 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21632 (while (re-search-forward "^(defun" nil t)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21633 (setq lengths-list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21634 (cons (count-words-in-defun) lengths-list)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21635 (kill-buffer buffer)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21636 lengths-list)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21637 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21638 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21639
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21640 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21641 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21642 (defun lengths-list-many-files (list-of-files)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21643 "Return list of lengths of defuns in LIST-OF-FILES."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21644 (let (lengths-list)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21645 ;;; @r{true-or-false-test}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21646 (while list-of-files
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21647 (setq lengths-list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21648 (append
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21649 lengths-list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21650 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21651 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21652 ;;; @r{Generate a lengths' list.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21653 (lengths-list-file
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21654 (expand-file-name (car list-of-files)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21655 ;;; @r{Make files' list shorter.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21656 (setq list-of-files (cdr list-of-files)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21657 ;;; @r{Return final value of lengths' list.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21658 lengths-list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21659 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21660 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21661
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21662 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21663 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21664 (defun defuns-per-range (sorted-lengths top-of-ranges)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21665 "SORTED-LENGTHS defuns in each TOP-OF-RANGES range."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21666 (let ((top-of-range (car top-of-ranges))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21667 (number-within-range 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21668 defuns-per-range-list)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21669 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21670
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21671 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21672 ;; @r{Outer loop.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21673 (while top-of-ranges
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21674
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21675 ;; @r{Inner loop.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21676 (while (and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21677 ;; @r{Need number for numeric test.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21678 (car sorted-lengths)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21679 (< (car sorted-lengths) top-of-range))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21680
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21681 ;; @r{Count number of definitions within current range.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21682 (setq number-within-range (1+ number-within-range))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21683 (setq sorted-lengths (cdr sorted-lengths)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21684 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21685
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21686 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21687 ;; @r{Exit inner loop but remain within outer loop.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21688
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21689 (setq defuns-per-range-list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21690 (cons number-within-range defuns-per-range-list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21691 (setq number-within-range 0) ; @r{Reset count to zero.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21692
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21693 ;; @r{Move to next range.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21694 (setq top-of-ranges (cdr top-of-ranges))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21695 ;; @r{Specify next top of range value.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21696 (setq top-of-range (car top-of-ranges)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21697 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21698
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21699 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21700 ;; @r{Exit outer loop and count the number of defuns larger than}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21701 ;; @r{ the largest top-of-range value.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21702 (setq defuns-per-range-list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21703 (cons
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21704 (length sorted-lengths)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21705 defuns-per-range-list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21706
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21707 ;; @r{Return a list of the number of definitions within each range,}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21708 ;; @r{ smallest to largest.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21709 (nreverse defuns-per-range-list)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21710 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21711 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21712
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21713 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21714 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21715 (defun column-of-graph (max-graph-height actual-height)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21716 "Return list of MAX-GRAPH-HEIGHT strings;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21717 ACTUAL-HEIGHT are graph-symbols.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21718 The graph-symbols are contiguous entries at the end
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21719 of the list.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21720 The list will be inserted as one column of a graph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21721 The strings are either graph-blank or graph-symbol."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21722 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21723
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21724 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21725 (let ((insert-list nil)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21726 (number-of-top-blanks
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21727 (- max-graph-height actual-height)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21728
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21729 ;; @r{Fill in @code{graph-symbols}.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21730 (while (> actual-height 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21731 (setq insert-list (cons graph-symbol insert-list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21732 (setq actual-height (1- actual-height)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21733 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21734
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21735 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21736 ;; @r{Fill in @code{graph-blanks}.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21737 (while (> number-of-top-blanks 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21738 (setq insert-list (cons graph-blank insert-list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21739 (setq number-of-top-blanks
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21740 (1- number-of-top-blanks)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21741
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21742 ;; @r{Return whole list.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21743 insert-list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21744 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21745 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21746
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21747 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21748 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21749 (defun Y-axis-element (number full-Y-label-width)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21750 "Construct a NUMBERed label element.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21751 A numbered element looks like this ` 5 - ',
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21752 and is padded as needed so all line up with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21753 the element for the largest number."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21754 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21755 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21756 (let* ((leading-spaces
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21757 (- full-Y-label-width
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21758 (length
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21759 (concat (number-to-string number)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21760 Y-axis-tic)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21761 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21762 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21763 (concat
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21764 (make-string leading-spaces ? )
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21765 (number-to-string number)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21766 Y-axis-tic)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21767 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21768 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21769
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21770 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21771 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21772 (defun print-Y-axis
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21773 (height full-Y-label-width &optional vertical-step)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21774 "Insert Y axis by HEIGHT and FULL-Y-LABEL-WIDTH.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21775 Height must be the maximum height of the graph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21776 Full width is the width of the highest label element.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21777 Optionally, print according to VERTICAL-STEP."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21778 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21779 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21780 ;; Value of height and full-Y-label-width
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21781 ;; are passed by `print-graph'.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21782 (let ((start (point)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21783 (insert-rectangle
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21784 (Y-axis-column height full-Y-label-width vertical-step))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21785 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21786 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21787 ;; @r{Place point ready for inserting graph.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21788 (goto-char start)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21789 ;; @r{Move point forward by value of} full-Y-label-width
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21790 (forward-char full-Y-label-width)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21791 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21792 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21793
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21794 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21795 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21796 (defun print-X-axis-tic-line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21797 (number-of-X-tics X-axis-leading-spaces X-axis-tic-element)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21798 "Print ticks for X axis."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21799 (insert X-axis-leading-spaces)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21800 (insert X-axis-tic-symbol) ; @r{Under first column.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21801 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21802 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21803 ;; @r{Insert second tic in the right spot.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21804 (insert (concat
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21805 (make-string
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21806 (- (* symbol-width X-axis-label-spacing)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21807 ;; @r{Insert white space up to second tic symbol.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21808 (* 2 (length X-axis-tic-symbol)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21809 ? )
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21810 X-axis-tic-symbol))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21811 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21812 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21813 ;; @r{Insert remaining ticks.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21814 (while (> number-of-X-tics 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21815 (insert X-axis-tic-element)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21816 (setq number-of-X-tics (1- number-of-X-tics))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21817 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21818 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21819
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21820 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21821 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21822 (defun X-axis-element (number)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21823 "Construct a numbered X axis element."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21824 (let ((leading-spaces
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21825 (- (* symbol-width X-axis-label-spacing)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21826 (length (number-to-string number)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21827 (concat (make-string leading-spaces ? )
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21828 (number-to-string number))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21829 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21830 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21831
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21832 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21833 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21834 (defun graph-body-print (numbers-list height symbol-width)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21835 "Print a bar graph of the NUMBERS-LIST.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21836 The numbers-list consists of the Y-axis values.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21837 HEIGHT is maximum height of graph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21838 SYMBOL-WIDTH is number of each column."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21839 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21840 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21841 (let (from-position)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21842 (while numbers-list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21843 (setq from-position (point))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21844 (insert-rectangle
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21845 (column-of-graph height (car numbers-list)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21846 (goto-char from-position)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21847 (forward-char symbol-width)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21848 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21849 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21850 ;; @r{Draw graph column by column.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21851 (sit-for 0)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21852 (setq numbers-list (cdr numbers-list)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21853 ;; @r{Place point for X axis labels.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21854 (forward-line height)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21855 (insert "\n")))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21856 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21857 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21858
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21859 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21860 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21861 (defun Y-axis-column
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21862 (height width-of-label &optional vertical-step)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21863 "Construct list of labels for Y axis.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21864 HEIGHT is maximum height of graph.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21865 WIDTH-OF-LABEL is maximum width of label.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21866 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21867 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21868 VERTICAL-STEP, an option, is a positive integer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21869 that specifies how much a Y axis label increments
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21870 for each line. For example, a step of 5 means
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21871 that each line is five units of the graph."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21872 (let (Y-axis
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21873 (number-per-line (or vertical-step 1)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21874 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21875 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21876 (while (> height 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21877 (if (zerop (% height Y-axis-label-spacing))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21878 ;; @r{Insert label.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21879 (setq Y-axis
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21880 (cons
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21881 (Y-axis-element
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21882 (* height number-per-line)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21883 width-of-label)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21884 Y-axis))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21885 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21886 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21887 ;; @r{Else, insert blanks.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21888 (setq Y-axis
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21889 (cons
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21890 (make-string width-of-label ? )
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21891 Y-axis)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21892 (setq height (1- height)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21893 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21894 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21895 ;; @r{Insert base line.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21896 (setq Y-axis (cons (Y-axis-element
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21897 (or vertical-step 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21898 width-of-label)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21899 Y-axis))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21900 (nreverse Y-axis)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21901 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21902 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21903
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21904 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21905 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21906 (defun print-X-axis-numbered-line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21907 (number-of-X-tics X-axis-leading-spaces
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21908 &optional horizontal-step)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21909 "Print line of X-axis numbers"
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21910 (let ((number X-axis-label-spacing)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21911 (horizontal-step (or horizontal-step 1)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21912 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21913 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21914 (insert X-axis-leading-spaces)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21915 ;; line up number
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21916 (delete-char (- (1- (length (number-to-string horizontal-step)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21917 (insert (concat
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21918 (make-string
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21919 ;; @r{Insert white space up to next number.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21920 (- (* symbol-width X-axis-label-spacing)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21921 (1- (length (number-to-string horizontal-step)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21922 2)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21923 ? )
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21924 (number-to-string (* number horizontal-step))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21925 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21926 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21927 ;; @r{Insert remaining numbers.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21928 (setq number (+ number X-axis-label-spacing))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21929 (while (> number-of-X-tics 1)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21930 (insert (X-axis-element (* number horizontal-step)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21931 (setq number (+ number X-axis-label-spacing))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21932 (setq number-of-X-tics (1- number-of-X-tics)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21933 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21934 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21935
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21936 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21937 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21938 (defun print-X-axis (numbers-list horizontal-step)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21939 "Print X axis labels to length of NUMBERS-LIST.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21940 Optionally, HORIZONTAL-STEP, a positive integer,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21941 specifies how much an X axis label increments for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21942 each column."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21943 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21944 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21945 ;; Value of symbol-width and full-Y-label-width
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21946 ;; are passed by `print-graph'.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21947 (let* ((leading-spaces
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21948 (make-string full-Y-label-width ? ))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21949 ;; symbol-width @r{is provided by} graph-body-print
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21950 (tic-width (* symbol-width X-axis-label-spacing))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21951 (X-length (length numbers-list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21952 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21953 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21954 (X-tic
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21955 (concat
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21956 (make-string
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21957 ;; @r{Make a string of blanks.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21958 (- (* symbol-width X-axis-label-spacing)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21959 (length X-axis-tic-symbol))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21960 ? )
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21961 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21962 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21963 ;; @r{Concatenate blanks with tic symbol.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21964 X-axis-tic-symbol))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21965 (tic-number
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21966 (if (zerop (% X-length tic-width))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21967 (/ X-length tic-width)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21968 (1+ (/ X-length tic-width)))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21969 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21970
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21971 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21972 (print-X-axis-tic-line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21973 tic-number leading-spaces X-tic)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21974 (insert "\n")
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21975 (print-X-axis-numbered-line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21976 tic-number leading-spaces horizontal-step)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21977 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21978 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21979
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21980 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21981 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21982 (defun one-fiftieth (full-range)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21983 "Return list, each number of which is 1/50th previous."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21984 (mapcar '(lambda (arg) (/ arg 50)) full-range))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21985 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21986 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21987
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21988 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21989 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21990 (defun print-graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21991 (numbers-list &optional vertical-step horizontal-step)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21992 "Print labelled bar graph of the NUMBERS-LIST.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21993 The numbers-list consists of the Y-axis values.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21994 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21995
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21996 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21997 Optionally, VERTICAL-STEP, a positive integer,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21998 specifies how much a Y axis label increments for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21999 each line. For example, a step of 5 means that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22000 each row is five units.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22001 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22002
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22003 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22004 Optionally, HORIZONTAL-STEP, a positive integer,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22005 specifies how much an X axis label increments for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22006 each column."
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22007 (let* ((symbol-width (length graph-blank))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22008 ;; @code{height} @r{is both the largest number}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22009 ;; @r{and the number with the most digits.}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22010 (height (apply 'max numbers-list))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22011 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22012 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22013 (height-of-top-line
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22014 (if (zerop (% height Y-axis-label-spacing))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22015 height
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22016 ;; @r{else}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22017 (* (1+ (/ height Y-axis-label-spacing))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22018 Y-axis-label-spacing)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22019 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22020 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22021 (vertical-step (or vertical-step 1))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22022 (full-Y-label-width
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22023 (length
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22024 (concat
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22025 (number-to-string
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22026 (* height-of-top-line vertical-step))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22027 Y-axis-tic))))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22028 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22029 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22030
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22031 (print-Y-axis
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22032 height-of-top-line full-Y-label-width vertical-step)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22033 (graph-body-print
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22034 numbers-list height-of-top-line symbol-width)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22035 (print-X-axis numbers-list horizontal-step)))
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22036 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22037 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22038 @c qqq
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22039 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22040
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22041 @page
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22042 @node Final printed graph, , Another Bug, Print Whole Graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22043 @appendixsubsec The Printed Graph
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22044
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22045 When made and installed, you can call the @code{print-graph} command
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22046 like this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22047 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22048
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22049 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22050 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22051 (print-graph fiftieth-list-for-graph 50 10)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22052 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22053 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22054 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22055
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22056 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22057 Here is the graph:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22058 @sp 2
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22059
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22060 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22061 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22062 1000 - *
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22063 **
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22064 **
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22065 **
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22066 **
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22067 750 - ***
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22068 ***
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22069 ***
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22070 ***
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22071 ****
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22072 500 - *****
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22073 ******
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22074 ******
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22075 ******
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22076 *******
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22077 250 - ********
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22078 ********* *
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22079 *********** *
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22080 ************* *
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22081 50 - ***************** * *
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22082 | | | | | | | |
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22083 10 50 100 150 200 250 300 350
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22084 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22085 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22086
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22087 @sp 2
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22088
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22089 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22090 The largest group of functions contain 10 -- 19 words and symbols each.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22091
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22092 @node Free Software and Free Manuals, GNU Free Documentation License, Full Graph, Top
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22093 @appendix Free Software and Free Manuals
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22094
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22095 @strong{by Richard M. Stallman}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22096 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22097
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22098 The biggest deficiency in free operating systems is not in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22099 software---it is the lack of good free manuals that we can include in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22100 these systems. Many of our most important programs do not come with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22101 full manuals. Documentation is an essential part of any software
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22102 package; when an important free software package does not come with a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22103 free manual, that is a major gap. We have many such gaps today.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22104
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22105 Once upon a time, many years ago, I thought I would learn Perl. I got
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22106 a copy of a free manual, but I found it hard to read. When I asked
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22107 Perl users about alternatives, they told me that there were better
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22108 introductory manuals---but those were not free.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22109
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22110 Why was this? The authors of the good manuals had written them for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22111 O'Reilly Associates, which published them with restrictive terms---no
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22112 copying, no modification, source files not available---which exclude
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22113 them from the free software community.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22114
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22115 That wasn't the first time this sort of thing has happened, and (to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22116 our community's great loss) it was far from the last. Proprietary
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22117 manual publishers have enticed a great many authors to restrict their
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22118 manuals since then. Many times I have heard a GNU user eagerly tell me
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22119 about a manual that he is writing, with which he expects to help the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22120 GNU project---and then had my hopes dashed, as he proceeded to explain
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22121 that he had signed a contract with a publisher that would restrict it
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22122 so that we cannot use it.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22123
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22124 Given that writing good English is a rare skill among programmers, we
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22125 can ill afford to lose manuals this way.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22126
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22127 @c (texinfo)uref
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22128 (The Free Software Foundation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22129 @uref{http://www.gnu.org/doc/doc.html#DescriptionsOfGNUDocumentation, ,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22130 sells printed copies} of free @uref{http://www.gnu.org/doc/doc.html,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22131 GNU manuals}, too.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22132
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22133 Free documentation, like free software, is a matter of freedom, not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22134 price. The problem with these manuals was not that O'Reilly Associates
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22135 charged a price for printed copies---that in itself is fine. (The Free
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22136 Software Foundation sells printed copies of free GNU manuals, too.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22137 But GNU manuals are available in source code form, while these manuals
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22138 are available only on paper. GNU manuals come with permission to copy
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22139 and modify; the Perl manuals do not. These restrictions are the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22140 problems.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22141
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22142 The criterion for a free manual is pretty much the same as for free
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22143 software: it is a matter of giving all users certain
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22144 freedoms. Redistribution (including commercial redistribution) must be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22145 permitted, so that the manual can accompany every copy of the program,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22146 on-line or on paper. Permission for modification is crucial too.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22147
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22148 As a general rule, I don't believe that it is essential for people to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22149 have permission to modify all sorts of articles and books. The issues
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22150 for writings are not necessarily the same as those for software. For
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22151 example, I don't think you or I are obliged to give permission to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22152 modify articles like this one, which describe our actions and our
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22153 views.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22154
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22155 But there is a particular reason why the freedom to modify is crucial
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22156 for documentation for free software. When people exercise their right
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22157 to modify the software, and add or change its features, if they are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22158 conscientious they will change the manual too---so they can provide
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22159 accurate and usable documentation with the modified program. A manual
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22160 which forbids programmers to be conscientious and finish the job, or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22161 more precisely requires them to write a new manual from scratch if
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22162 they change the program, does not fill our community's needs.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22163
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22164 While a blanket prohibition on modification is unacceptable, some
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22165 kinds of limits on the method of modification pose no problem. For
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22166 example, requirements to preserve the original author's copyright
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22167 notice, the distribution terms, or the list of authors, are ok. It is
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22168 also no problem to require modified versions to include notice that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22169 they were modified, even to have entire sections that may not be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22170 deleted or changed, as long as these sections deal with nontechnical
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22171 topics. (Some GNU manuals have them.)
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22172
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22173 These kinds of restrictions are not a problem because, as a practical
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22174 matter, they don't stop the conscientious programmer from adapting the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22175 manual to fit the modified program. In other words, they don't block
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22176 the free software community from making full use of the manual.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22177
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22178 However, it must be possible to modify all the technical content of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22179 the manual, and then distribute the result in all the usual media,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22180 through all the usual channels; otherwise, the restrictions do block
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22181 the community, the manual is not free, and so we need another manual.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22182
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22183 Unfortunately, it is often hard to find someone to write another
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22184 manual when a proprietary manual exists. The obstacle is that many
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22185 users think that a proprietary manual is good enough---so they don't
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22186 see the need to write a free manual. They do not see that the free
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22187 operating system has a gap that needs filling.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22188
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22189 Why do users think that proprietary manuals are good enough? Some have
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22190 not considered the issue. I hope this article will do something to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22191 change that.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22192
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22193 Other users consider proprietary manuals acceptable for the same
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22194 reason so many people consider proprietary software acceptable: they
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22195 judge in purely practical terms, not using freedom as a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22196 criterion. These people are entitled to their opinions, but since
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22197 those opinions spring from values which do not include freedom, they
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22198 are no guide for those of us who do value freedom.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22199
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22200 Please spread the word about this issue. We continue to lose manuals
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22201 to proprietary publishing. If we spread the word that proprietary
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22202 manuals are not sufficient, perhaps the next person who wants to help
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22203 GNU by writing documentation will realize, before it is too late, that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22204 he must above all make it free.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22205
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22206 We can also encourage commercial publishers to sell free, copylefted
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22207 manuals instead of proprietary ones. One way you can help this is to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22208 check the distribution terms of a manual before you buy it, and prefer
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22209 copylefted manuals to non-copylefted ones.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22210
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22211 @sp 2
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22212 @noindent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22213 Note: The Free Software Foundation maintains a page on its Web site
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22214 that lists free books available from other publishers:@*
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22215 @uref{http://www.gnu.org/doc/other-free-books.html}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22216
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22217 @node GNU Free Documentation License, Index, Free Software and Free Manuals, Top
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22218 @appendix GNU Free Documentation License
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22219
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22220 @cindex FDL, GNU Free Documentation License
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22221 @center Version 1.2, November 2002
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22222
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22223 @display
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22224 Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22225 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22226
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22227 Everyone is permitted to copy and distribute verbatim copies
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22228 of this license document, but changing it is not allowed.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22229 @end display
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22230
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22231 @enumerate 0
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22232 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22233 PREAMBLE
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22234
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22235 The purpose of this License is to make a manual, textbook, or other
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22236 functional and useful document @dfn{free} in the sense of freedom: to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22237 assure everyone the effective freedom to copy and redistribute it,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22238 with or without modifying it, either commercially or noncommercially.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22239 Secondarily, this License preserves for the author and publisher a way
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22240 to get credit for their work, while not being considered responsible
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22241 for modifications made by others.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22242
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22243 This License is a kind of ``copyleft'', which means that derivative
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22244 works of the document must themselves be free in the same sense. It
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22245 complements the GNU General Public License, which is a copyleft
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22246 license designed for free software.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22247
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22248 We have designed this License in order to use it for manuals for free
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22249 software, because free software needs free documentation: a free
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22250 program should come with manuals providing the same freedoms that the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22251 software does. But this License is not limited to software manuals;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22252 it can be used for any textual work, regardless of subject matter or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22253 whether it is published as a printed book. We recommend this License
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22254 principally for works whose purpose is instruction or reference.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22255
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22256 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22257 APPLICABILITY AND DEFINITIONS
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22258
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22259 This License applies to any manual or other work, in any medium, that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22260 contains a notice placed by the copyright holder saying it can be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22261 distributed under the terms of this License. Such a notice grants a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22262 world-wide, royalty-free license, unlimited in duration, to use that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22263 work under the conditions stated herein. The ``Document'', below,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22264 refers to any such manual or work. Any member of the public is a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22265 licensee, and is addressed as ``you''. You accept the license if you
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22266 copy, modify or distribute the work in a way requiring permission
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22267 under copyright law.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22268
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22269 A ``Modified Version'' of the Document means any work containing the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22270 Document or a portion of it, either copied verbatim, or with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22271 modifications and/or translated into another language.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22272
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22273 A ``Secondary Section'' is a named appendix or a front-matter section
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22274 of the Document that deals exclusively with the relationship of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22275 publishers or authors of the Document to the Document's overall
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22276 subject (or to related matters) and contains nothing that could fall
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22277 directly within that overall subject. (Thus, if the Document is in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22278 part a textbook of mathematics, a Secondary Section may not explain
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22279 any mathematics.) The relationship could be a matter of historical
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22280 connection with the subject or with related matters, or of legal,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22281 commercial, philosophical, ethical or political position regarding
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22282 them.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22283
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22284 The ``Invariant Sections'' are certain Secondary Sections whose titles
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22285 are designated, as being those of Invariant Sections, in the notice
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22286 that says that the Document is released under this License. If a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22287 section does not fit the above definition of Secondary then it is not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22288 allowed to be designated as Invariant. The Document may contain zero
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22289 Invariant Sections. If the Document does not identify any Invariant
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22290 Sections then there are none.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22291
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22292 The ``Cover Texts'' are certain short passages of text that are listed,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22293 as Front-Cover Texts or Back-Cover Texts, in the notice that says that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22294 the Document is released under this License. A Front-Cover Text may
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22295 be at most 5 words, and a Back-Cover Text may be at most 25 words.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22296
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22297 A ``Transparent'' copy of the Document means a machine-readable copy,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22298 represented in a format whose specification is available to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22299 general public, that is suitable for revising the document
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22300 straightforwardly with generic text editors or (for images composed of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22301 pixels) generic paint programs or (for drawings) some widely available
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22302 drawing editor, and that is suitable for input to text formatters or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22303 for automatic translation to a variety of formats suitable for input
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22304 to text formatters. A copy made in an otherwise Transparent file
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22305 format whose markup, or absence of markup, has been arranged to thwart
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22306 or discourage subsequent modification by readers is not Transparent.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22307 An image format is not Transparent if used for any substantial amount
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22308 of text. A copy that is not ``Transparent'' is called ``Opaque''.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22309
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22310 Examples of suitable formats for Transparent copies include plain
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22311 @sc{ascii} without markup, Texinfo input format, La@TeX{} input
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22312 format, @acronym{SGML} or @acronym{XML} using a publicly available
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22313 @acronym{DTD}, and standard-conforming simple @acronym{HTML},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22314 PostScript or @acronym{PDF} designed for human modification. Examples
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22315 of transparent image formats include @acronym{PNG}, @acronym{XCF} and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22316 @acronym{JPG}. Opaque formats include proprietary formats that can be
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22317 read and edited only by proprietary word processors, @acronym{SGML} or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22318 @acronym{XML} for which the @acronym{DTD} and/or processing tools are
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22319 not generally available, and the machine-generated @acronym{HTML},
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22320 PostScript or @acronym{PDF} produced by some word processors for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22321 output purposes only.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22322
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22323 The ``Title Page'' means, for a printed book, the title page itself,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22324 plus such following pages as are needed to hold, legibly, the material
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22325 this License requires to appear in the title page. For works in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22326 formats which do not have any title page as such, ``Title Page'' means
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22327 the text near the most prominent appearance of the work's title,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22328 preceding the beginning of the body of the text.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22329
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22330 A section ``Entitled XYZ'' means a named subunit of the Document whose
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22331 title either is precisely XYZ or contains XYZ in parentheses following
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22332 text that translates XYZ in another language. (Here XYZ stands for a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22333 specific section name mentioned below, such as ``Acknowledgements'',
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22334 ``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22335 of such a section when you modify the Document means that it remains a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22336 section ``Entitled XYZ'' according to this definition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22337
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22338 The Document may include Warranty Disclaimers next to the notice which
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22339 states that this License applies to the Document. These Warranty
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22340 Disclaimers are considered to be included by reference in this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22341 License, but only as regards disclaiming warranties: any other
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22342 implication that these Warranty Disclaimers may have is void and has
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22343 no effect on the meaning of this License.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22344
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22345 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22346 VERBATIM COPYING
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22347
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22348 You may copy and distribute the Document in any medium, either
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22349 commercially or noncommercially, provided that this License, the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22350 copyright notices, and the license notice saying this License applies
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22351 to the Document are reproduced in all copies, and that you add no other
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22352 conditions whatsoever to those of this License. You may not use
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22353 technical measures to obstruct or control the reading or further
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22354 copying of the copies you make or distribute. However, you may accept
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22355 compensation in exchange for copies. If you distribute a large enough
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22356 number of copies you must also follow the conditions in section 3.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22357
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22358 You may also lend copies, under the same conditions stated above, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22359 you may publicly display copies.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22360
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22361 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22362 COPYING IN QUANTITY
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22363
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22364 If you publish printed copies (or copies in media that commonly have
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22365 printed covers) of the Document, numbering more than 100, and the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22366 Document's license notice requires Cover Texts, you must enclose the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22367 copies in covers that carry, clearly and legibly, all these Cover
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22368 Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22369 the back cover. Both covers must also clearly and legibly identify
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22370 you as the publisher of these copies. The front cover must present
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22371 the full title with all words of the title equally prominent and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22372 visible. You may add other material on the covers in addition.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22373 Copying with changes limited to the covers, as long as they preserve
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22374 the title of the Document and satisfy these conditions, can be treated
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22375 as verbatim copying in other respects.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22376
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22377 If the required texts for either cover are too voluminous to fit
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22378 legibly, you should put the first ones listed (as many as fit
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22379 reasonably) on the actual cover, and continue the rest onto adjacent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22380 pages.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22381
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22382 If you publish or distribute Opaque copies of the Document numbering
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22383 more than 100, you must either include a machine-readable Transparent
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22384 copy along with each Opaque copy, or state in or with each Opaque copy
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22385 a computer-network location from which the general network-using
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22386 public has access to download using public-standard network protocols
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22387 a complete Transparent copy of the Document, free of added material.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22388 If you use the latter option, you must take reasonably prudent steps,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22389 when you begin distribution of Opaque copies in quantity, to ensure
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22390 that this Transparent copy will remain thus accessible at the stated
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22391 location until at least one year after the last time you distribute an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22392 Opaque copy (directly or through your agents or retailers) of that
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22393 edition to the public.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22394
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22395 It is requested, but not required, that you contact the authors of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22396 Document well before redistributing any large number of copies, to give
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22397 them a chance to provide you with an updated version of the Document.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22398
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22399 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22400 MODIFICATIONS
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22401
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22402 You may copy and distribute a Modified Version of the Document under
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22403 the conditions of sections 2 and 3 above, provided that you release
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22404 the Modified Version under precisely this License, with the Modified
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22405 Version filling the role of the Document, thus licensing distribution
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22406 and modification of the Modified Version to whoever possesses a copy
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22407 of it. In addition, you must do these things in the Modified Version:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22408
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22409 @enumerate A
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22410 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22411 Use in the Title Page (and on the covers, if any) a title distinct
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22412 from that of the Document, and from those of previous versions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22413 (which should, if there were any, be listed in the History section
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22414 of the Document). You may use the same title as a previous version
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22415 if the original publisher of that version gives permission.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22416
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22417 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22418 List on the Title Page, as authors, one or more persons or entities
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22419 responsible for authorship of the modifications in the Modified
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22420 Version, together with at least five of the principal authors of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22421 Document (all of its principal authors, if it has fewer than five),
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22422 unless they release you from this requirement.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22423
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22424 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22425 State on the Title page the name of the publisher of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22426 Modified Version, as the publisher.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22427
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22428 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22429 Preserve all the copyright notices of the Document.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22430
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22431 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22432 Add an appropriate copyright notice for your modifications
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22433 adjacent to the other copyright notices.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22434
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22435 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22436 Include, immediately after the copyright notices, a license notice
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22437 giving the public permission to use the Modified Version under the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22438 terms of this License, in the form shown in the Addendum below.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22439
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22440 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22441 Preserve in that license notice the full lists of Invariant Sections
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22442 and required Cover Texts given in the Document's license notice.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22443
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22444 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22445 Include an unaltered copy of this License.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22446
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22447 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22448 Preserve the section Entitled ``History'', Preserve its Title, and add
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22449 to it an item stating at least the title, year, new authors, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22450 publisher of the Modified Version as given on the Title Page. If
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22451 there is no section Entitled ``History'' in the Document, create one
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22452 stating the title, year, authors, and publisher of the Document as
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22453 given on its Title Page, then add an item describing the Modified
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22454 Version as stated in the previous sentence.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22455
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22456 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22457 Preserve the network location, if any, given in the Document for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22458 public access to a Transparent copy of the Document, and likewise
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22459 the network locations given in the Document for previous versions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22460 it was based on. These may be placed in the ``History'' section.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22461 You may omit a network location for a work that was published at
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22462 least four years before the Document itself, or if the original
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22463 publisher of the version it refers to gives permission.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22464
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22465 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22466 For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22467 the Title of the section, and preserve in the section all the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22468 substance and tone of each of the contributor acknowledgements and/or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22469 dedications given therein.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22470
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22471 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22472 Preserve all the Invariant Sections of the Document,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22473 unaltered in their text and in their titles. Section numbers
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22474 or the equivalent are not considered part of the section titles.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22475
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22476 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22477 Delete any section Entitled ``Endorsements''. Such a section
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22478 may not be included in the Modified Version.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22479
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22480 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22481 Do not retitle any existing section to be Entitled ``Endorsements'' or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22482 to conflict in title with any Invariant Section.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22483
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22484 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22485 Preserve any Warranty Disclaimers.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22486 @end enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22487
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22488 If the Modified Version includes new front-matter sections or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22489 appendices that qualify as Secondary Sections and contain no material
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22490 copied from the Document, you may at your option designate some or all
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22491 of these sections as invariant. To do this, add their titles to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22492 list of Invariant Sections in the Modified Version's license notice.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22493 These titles must be distinct from any other section titles.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22494
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22495 You may add a section Entitled ``Endorsements'', provided it contains
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22496 nothing but endorsements of your Modified Version by various
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22497 parties---for example, statements of peer review or that the text has
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22498 been approved by an organization as the authoritative definition of a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22499 standard.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22500
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22501 You may add a passage of up to five words as a Front-Cover Text, and a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22502 passage of up to 25 words as a Back-Cover Text, to the end of the list
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22503 of Cover Texts in the Modified Version. Only one passage of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22504 Front-Cover Text and one of Back-Cover Text may be added by (or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22505 through arrangements made by) any one entity. If the Document already
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22506 includes a cover text for the same cover, previously added by you or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22507 by arrangement made by the same entity you are acting on behalf of,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22508 you may not add another; but you may replace the old one, on explicit
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22509 permission from the previous publisher that added the old one.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22510
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22511 The author(s) and publisher(s) of the Document do not by this License
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22512 give permission to use their names for publicity for or to assert or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22513 imply endorsement of any Modified Version.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22514
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22515 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22516 COMBINING DOCUMENTS
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22517
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22518 You may combine the Document with other documents released under this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22519 License, under the terms defined in section 4 above for modified
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22520 versions, provided that you include in the combination all of the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22521 Invariant Sections of all of the original documents, unmodified, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22522 list them all as Invariant Sections of your combined work in its
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22523 license notice, and that you preserve all their Warranty Disclaimers.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22524
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22525 The combined work need only contain one copy of this License, and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22526 multiple identical Invariant Sections may be replaced with a single
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22527 copy. If there are multiple Invariant Sections with the same name but
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22528 different contents, make the title of each such section unique by
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22529 adding at the end of it, in parentheses, the name of the original
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22530 author or publisher of that section if known, or else a unique number.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22531 Make the same adjustment to the section titles in the list of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22532 Invariant Sections in the license notice of the combined work.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22533
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22534 In the combination, you must combine any sections Entitled ``History''
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22535 in the various original documents, forming one section Entitled
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22536 ``History''; likewise combine any sections Entitled ``Acknowledgements'',
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22537 and any sections Entitled ``Dedications''. You must delete all
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22538 sections Entitled ``Endorsements.''
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22539
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22540 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22541 COLLECTIONS OF DOCUMENTS
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22542
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22543 You may make a collection consisting of the Document and other documents
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22544 released under this License, and replace the individual copies of this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22545 License in the various documents with a single copy that is included in
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22546 the collection, provided that you follow the rules of this License for
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22547 verbatim copying of each of the documents in all other respects.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22548
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22549 You may extract a single document from such a collection, and distribute
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22550 it individually under this License, provided you insert a copy of this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22551 License into the extracted document, and follow this License in all
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22552 other respects regarding verbatim copying of that document.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22553
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22554 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22555 AGGREGATION WITH INDEPENDENT WORKS
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22556
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22557 A compilation of the Document or its derivatives with other separate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22558 and independent documents or works, in or on a volume of a storage or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22559 distribution medium, is called an ``aggregate'' if the copyright
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22560 resulting from the compilation is not used to limit the legal rights
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22561 of the compilation's users beyond what the individual works permit.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22562 When the Document is included in an aggregate, this License does not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22563 apply to the other works in the aggregate which are not themselves
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22564 derivative works of the Document.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22565
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22566 If the Cover Text requirement of section 3 is applicable to these
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22567 copies of the Document, then if the Document is less than one half of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22568 the entire aggregate, the Document's Cover Texts may be placed on
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22569 covers that bracket the Document within the aggregate, or the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22570 electronic equivalent of covers if the Document is in electronic form.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22571 Otherwise they must appear on printed covers that bracket the whole
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22572 aggregate.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22573
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22574 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22575 TRANSLATION
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22576
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22577 Translation is considered a kind of modification, so you may
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22578 distribute translations of the Document under the terms of section 4.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22579 Replacing Invariant Sections with translations requires special
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22580 permission from their copyright holders, but you may include
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22581 translations of some or all Invariant Sections in addition to the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22582 original versions of these Invariant Sections. You may include a
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22583 translation of this License, and all the license notices in the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22584 Document, and any Warranty Disclaimers, provided that you also include
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22585 the original English version of this License and the original versions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22586 of those notices and disclaimers. In case of a disagreement between
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22587 the translation and the original version of this License or a notice
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22588 or disclaimer, the original version will prevail.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22589
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22590 If a section in the Document is Entitled ``Acknowledgements'',
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22591 ``Dedications'', or ``History'', the requirement (section 4) to Preserve
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22592 its Title (section 1) will typically require changing the actual
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22593 title.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22594
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22595 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22596 TERMINATION
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22597
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22598 You may not copy, modify, sublicense, or distribute the Document except
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22599 as expressly provided for under this License. Any other attempt to
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22600 copy, modify, sublicense or distribute the Document is void, and will
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22601 automatically terminate your rights under this License. However,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22602 parties who have received copies, or rights, from you under this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22603 License will not have their licenses terminated so long as such
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22604 parties remain in full compliance.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22605
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22606 @item
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22607 FUTURE REVISIONS OF THIS LICENSE
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22608
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22609 The Free Software Foundation may publish new, revised versions
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22610 of the GNU Free Documentation License from time to time. Such new
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22611 versions will be similar in spirit to the present version, but may
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22612 differ in detail to address new problems or concerns. See
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22613 @uref{http://www.gnu.org/copyleft/}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22614
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22615 Each version of the License is given a distinguishing version number.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22616 If the Document specifies that a particular numbered version of this
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22617 License ``or any later version'' applies to it, you have the option of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22618 following the terms and conditions either of that specified version or
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22619 of any later version that has been published (not as a draft) by the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22620 Free Software Foundation. If the Document does not specify a version
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22621 number of this License, you may choose any version ever published (not
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22622 as a draft) by the Free Software Foundation.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22623 @end enumerate
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22624
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22625 @page
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22626 @appendixsubsec ADDENDUM: How to use this License for your documents
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22627
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22628 To use this License in a document you have written, include a copy of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22629 the License in the document and put the following copyright and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22630 license notices just after the title page:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22631
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22632 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22633 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22634 Copyright (C) @var{year} @var{your name}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22635 Permission is granted to copy, distribute and/or modify this document
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22636 under the terms of the GNU Free Documentation License, Version 1.2
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22637 or any later version published by the Free Software Foundation;
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22638 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22639 A copy of the license is included in the section entitled ``GNU
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22640 Free Documentation License''.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22641 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22642 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22643
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22644 If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22645 replace the ``with...Texts.'' line with this:
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22646
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22647 @smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22648 @group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22649 with the Invariant Sections being @var{list their titles}, with
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22650 the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22651 being @var{list}.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22652 @end group
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22653 @end smallexample
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22654
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22655 If you have Invariant Sections without Cover Texts, or some other
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22656 combination of the three, merge those two alternatives to suit the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22657 situation.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22658
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22659 If your document contains nontrivial examples of program code, we
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22660 recommend releasing these examples in parallel under your choice of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22661 free software license, such as the GNU General Public License,
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22662 to permit their use in free software.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22663
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22664 @node Index, About the Author, GNU Free Documentation License, Top
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22665 @comment node-name, next, previous, up
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22666 @unnumbered Index
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22667
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22668 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22669 MENU ENTRY: NODE NAME.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22670 @end ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22671
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22672 @printindex cp
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22673
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22674 @iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22675 @c Place biographical information on right-hand (verso) page
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22676
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22677 @tex
98525
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
22678 \par\vfill\supereject
83955
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22679 \ifodd\pageno
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22680 \global\evenheadline={\hfil} \global\evenfootline={\hfil}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22681 \global\oddheadline={\hfil} \global\oddfootline={\hfil}
98525
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
22682 %\page\hbox{}\page
83955
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22683 \else
98525
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
22684 % \par\vfill\supereject
83955
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22685 \global\evenheadline={\hfil} \global\evenfootline={\hfil}
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22686 \global\oddheadline={\hfil} \global\oddfootline={\hfil}
98525
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
22687 %\page\hbox{}%\page
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
22688 %\page\hbox{}%\page
83955
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22689 \fi
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22690 @end tex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22691
98525
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
22692 @c page
83955
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22693 @w{ }
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22694
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22695 @c ================ Biographical information ================
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22696
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22697 @w{ }
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22698 @sp 8
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22699 @center About the Author
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22700 @sp 1
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22701 @end iftex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22702
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22703 @ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22704 @node About the Author, , Index, Top
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22705 @unnumbered About the Author
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22706 @end ifnottex
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22707
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22708 @quotation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22709 Robert J. Chassell has worked with GNU Emacs since 1985. He writes
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22710 and edits, teaches Emacs and Emacs Lisp, and speaks throughout the
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22711 world on software freedom. Chassell was a founding Director and
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22712 Treasurer of the Free Software Foundation, Inc. He is co-author of
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22713 the @cite{Texinfo} manual, and has edited more than a dozen other
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22714 books. He graduated from Cambridge University, in England. He has an
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22715 abiding interest in social and economic history and flies his own
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22716 airplane.
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22717 @end quotation
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22718
98525
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
22719 @c @page
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
22720 @c @w{ }
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
22721 @c
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
22722 @c @c Prevent page number on blank verso, so eject it first.
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
22723 @c @tex
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
22724 @c \par\vfill\supereject
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
22725 @c @end tex
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
22726
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
22727 @c @iftex
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
22728 @c @headings off
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
22729 @c @evenheading @thispage @| @| @thistitle
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
22730 @c @oddheading @| @| @thispage
b6395ec3de45 formatting fixes for new printed edition
Karl Berry <karl@gnu.org>
parents: 94896
diff changeset
22731 @c @end iftex
83955
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22732
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22733 @bye
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22734
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22735 @ignore
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22736 arch-tag: da1a2154-531f-43a8-8e33-fc7faad10acf
14bd8cfd94a6 Move here from ../../lispintro/
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22737 @end ignore