Mercurial > emacs
annotate lispintro/emacs-lisp-intro.texi @ 46343:fb71432c8a02
(command_loop_1): Invert check on Vmemory_full.
author | Kim F. Storm <storm@cua.dk> |
---|---|
date | Fri, 12 Jul 2002 23:47:31 +0000 |
parents | 046819540e6d |
children | ddbe3ea04f58 |
rev | line source |
---|---|
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1 \input texinfo @c -*-texinfo-*- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2 @comment %**start of header |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3 @setfilename ../info/eintr |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4 @c sethtmlfilename emacs-lisp-intro.html |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5 @settitle Programming in Emacs Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6 @syncodeindex vr cp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7 @syncodeindex fn cp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8 @setchapternewpage odd |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9 @finalout |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11 @c --------- |
41499
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
12 @c <<<< For hard copy printing, this file is now |
42562
fb149efd0c72
Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents:
42506
diff
changeset
|
13 @c set for smallbook, which works for all sizes |
41499
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
14 @c of paper, and with Postscript figures >>>> |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
15 @smallbook |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
16 @clear largebook |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17 @set print-postscript-figures |
41499
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
18 @c set largebook |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
19 @c clear print-postscript-figures |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20 @c --------- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
22 @comment %**end of header |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
23 |
45663
046819540e6d
Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents:
44899
diff
changeset
|
24 @set edition-number 2.06 |
046819540e6d
Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents:
44899
diff
changeset
|
25 @set update-date 2002 Jun 6 |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
26 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
27 @ignore |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
28 ## Summary of shell commands to create various output formats: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
29 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
30 ## Info output |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
31 makeinfo --no-split --paragraph-indent=0 --verbose emacs-lisp-intro.texi |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
32 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
33 ## DVI output |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
34 texi2dvi emacs-lisp-intro.texi |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
35 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
36 ## HTML output |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
37 makeinfo --html --no-split --verbose emacs-lisp-intro.texi |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
38 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
39 ## Plain text output |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
40 makeinfo --fill-column=70 --no-split --paragraph-indent=0 \ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
41 --verbose --no-headers --output=emacs-lisp-intro.txt emacs-lisp-intro.texi |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
42 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
43 @end ignore |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
44 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
45 @c ================ Included Figures ================ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
46 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
47 @c Set print-postscript-figures if you print PostScript figures. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
48 @c If you clear this, the ten figures will be printed as ASCII diagrams. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
49 @c (This is not relevant to Info, since Info only handles ASCII.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
50 @c Your site may require editing changes to print PostScript; in this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
51 @c case, search for `print-postscript-figures' and make appropriate changes. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
52 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
53 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
54 @c ================ How to Create an Info file ================ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
55 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
56 @c If you have `makeinfo' installed, run the following command |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
57 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
58 @c makeinfo emacs-lisp-intro.texi |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
59 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
60 @c or, if you want a single, large Info file, and no paragraph indents: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
61 @c makeinfo --no-split --paragraph-indent=0 --verbose emacs-lisp-intro.texi |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
62 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
63 @c After creating the Info file, edit your Info `dir' file, if the |
41674
ea1354316d4f
Fixed typographic error.
Robert J. Chassell <bob@rattlesnake.com>
parents:
41670
diff
changeset
|
64 @c `dircategory' section below does not enable your system to |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
65 @c install the manual automatically. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
66 @c (The `dir' file is often in the `/usr/local/info/' directory.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
67 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
68 @c ================ How to Create an HTML file ================ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
69 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
70 @c To convert to HTML format |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
71 @c makeinfo --html --no-split --verbose emacs-lisp-intro.texi |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
72 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
73 @c ================ How to Print a Book in Various Sizes ================ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
74 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
75 @c This book can be printed in any of three different sizes. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
76 @c In the above header, set @-commands appropriately. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
77 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
78 @c 7 by 9.25 inches: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
79 @c @smallbook |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
80 @c @clear largebook |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
81 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
82 @c 8.5 by 11 inches: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
83 @c @c smallbook |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
84 @c @set largebook |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
85 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
86 @c European A4 size paper: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
87 @c @c smallbook |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
88 @c @afourpaper |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
89 @c @set largebook |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
90 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
91 @c ================ How to Typeset and Print ================ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
92 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
93 @c If you do not include PostScript figures, run either of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
94 @c following command sequences, or similar commands suited to your |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
95 @c system: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
96 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
97 @c texi2dvi emacs-lisp-intro.texi |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
98 @c lpr -d emacs-lisp-intro.dvi |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
99 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
100 @c or else: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
101 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
102 @c tex emacs-lisp-intro.texi |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
103 @c texindex emacs-lisp-intro.?? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
104 @c tex emacs-lisp-intro.texi |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
105 @c lpr -d emacs-lisp-intro.dvi |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
106 |
41499
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
107 @c If you include the PostScript figures, and you have old software, |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
108 @c you may need to convert the .dvi file to a .ps file before |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
109 @c printing. Run either of the following command sequences, or one |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
110 @c similar: |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
111 @c |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
112 @c dvips -f < emacs-lisp-intro.dvi > emacs-lisp-intro.ps |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
113 @c |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
114 @c or else: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
115 @c |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
116 @c postscript -p < emacs-lisp-intro.dvi > emacs-lisp-intro.ps |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
117 @c |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
118 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
119 @c (Note: if you edit the book so as to change the length of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
120 @c table of contents, you may have to change the value of `pageno' below.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
121 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
122 @c ================ End of Formatting Sections ================ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
123 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
124 @c For next or subsequent edition: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
125 @c create function using with-output-to-temp-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
126 @c create a major mode, with keymaps |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
127 @c run an asynchronous process, like grep or diff |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
128 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
129 @c For smallbook format, use smaller than normal amounts of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
130 @c whitespace between chapters, sections, and paragraphs. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
131 @tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
132 \global\chapheadingskip = 15pt plus 4pt minus 2pt |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
133 \global\secheadingskip = 12pt plus 3pt minus 2pt |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
134 \global\subsecheadingskip = 9pt plus 2pt minus 2pt \global\parskip 2pt |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
135 plus 1pt |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
136 @end tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
137 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
138 @c For 8.5 by 11 inch format: do not use such a small amount of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
139 @c whitespace between paragraphs as above: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
140 @ifset largebook |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
141 @tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
142 \global\parskip 6pt plus 1pt |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
143 @end tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
144 @end ifset |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
145 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
146 @c For all sized formats: print within-book cross |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
147 @c reference with ``...'' rather than [...] |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
148 @tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
149 % Need following so comma appears after section numbers. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
150 \global\def\Ysectionnumberandtype{% |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
151 \ifnum\secno=0 \putwordChapter\xreftie\the\chapno, \space % |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
152 \else \ifnum \subsecno=0 \putwordSection\xreftie\the\chapno.\the\secno, \space % |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
153 \else \ifnum \subsubsecno=0 % |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
154 \putwordSection\xreftie\the\chapno.\the\secno.\the\subsecno, \space % |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
155 \else % |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
156 \putwordSection\xreftie\the\chapno.\the\secno.\the\subsecno.\the\subsubsecno, \space% |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
157 \fi \fi \fi } |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
158 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
159 \global\def\Yappendixletterandtype{% |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
160 \ifnum\secno=0 \putwordAppendix\xreftie'char\the\appendixno{}, \space% |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
161 \else \ifnum \subsecno=0 \putwordSection\xreftie'char\the\appendixno.\the\secno, \space % |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
162 \else \ifnum \subsubsecno=0 % |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
163 \putwordSection\xreftie'char\the\appendixno.\the\secno.\the\subsecno, \space % |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
164 \else % |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
165 \putwordSection\xreftie'char\the\appendixno.\the\secno.\the\subsecno.\the\subsubsecno, \space % |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
166 \fi \fi \fi } |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
167 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
168 \global\def\xrefX[#1,#2,#3,#4,#5,#6]{\begingroup |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
169 \def\printedmanual{\ignorespaces #5}% |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
170 \def\printednodename{\ignorespaces #3}% |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
171 \setbox1=\hbox{\printedmanual}% |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
172 \setbox0=\hbox{\printednodename}% |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
173 \ifdim \wd0 = 0pt |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
174 % No printed node name was explicitly given. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
175 \ifx\SETxref-automatic-section-title\relax % |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
176 % Use the actual chapter/section title appear inside |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
177 % the square brackets. Use the real section title if we have it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
178 \ifdim \wd1>0pt% |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
179 % It is in another manual, so we don't have it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
180 \def\printednodename{\ignorespaces #1}% |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
181 \else |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
182 \ifhavexrefs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
183 % We know the real title if we have the xref values. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
184 \def\printednodename{\refx{#1-title}}% |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
185 \else |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
186 % Otherwise just copy the Info node name. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
187 \def\printednodename{\ignorespaces #1}% |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
188 \fi% |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
189 \fi |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
190 \def\printednodename{#1-title}% |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
191 \else |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
192 % Use the node name inside the square brackets. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
193 \def\printednodename{\ignorespaces #1}% |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
194 \fi |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
195 \fi |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
196 % |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
197 % If we use \unhbox0 and \unhbox1 to print the node names, TeX does not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
198 % insert empty discretionaries after hyphens, which means that it will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
199 % not find a line break at a hyphen in a node names. Since some manuals |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
200 % are best written with fairly long node names, containing hyphens, this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
201 % is a loss. Therefore, we give the text of the node name again, so it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
202 % is as if TeX is seeing it for the first time. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
203 \ifdim \wd1 > 0pt |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
204 \putwordsection{} ``\printednodename'' in \cite{\printedmanual}% |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
205 \else |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
206 % _ (for example) has to be the character _ for the purposes of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
207 % control sequence corresponding to the node, but it has to expand |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
208 % into the usual \leavevmode...\vrule stuff for purposes of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
209 % printing. So we \turnoffactive for the \refx-snt, back on for the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
210 % printing, back off for the \refx-pg. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
211 {\turnoffactive \refx{#1-snt}{}}% |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
212 % \space [\printednodename],\space % <= original |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
213 % \putwordsection{} ``\printednodename'',\space |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
214 ``\printednodename'',\space |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
215 \turnoffactive \putwordpage\tie\refx{#1-pg}{}% |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
216 \fi |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
217 \endgroup} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
218 @end tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
219 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
220 @c ---------------------------------------------------- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
221 |
41670
b4c633081255
(Index): @ignore extraneous text.
Eli Zaretskii <eliz@gnu.org>
parents:
41499
diff
changeset
|
222 @dircategory Emacs |
b4c633081255
(Index): @ignore extraneous text.
Eli Zaretskii <eliz@gnu.org>
parents:
41499
diff
changeset
|
223 @direntry |
b4c633081255
(Index): @ignore extraneous text.
Eli Zaretskii <eliz@gnu.org>
parents:
41499
diff
changeset
|
224 * Emacs Lisp Intro: (eintr). |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
225 A simple introduction to Emacs Lisp programming. |
41670
b4c633081255
(Index): @ignore extraneous text.
Eli Zaretskii <eliz@gnu.org>
parents:
41499
diff
changeset
|
226 @end direntry |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
227 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
228 @ifinfo |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
229 This is an introduction to @cite{Programming in Emacs Lisp}, for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
230 people who are not programmers. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
231 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
232 Edition @value{edition-number}, @value{update-date} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
233 |
42562
fb149efd0c72
Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents:
42506
diff
changeset
|
234 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1997, 2001, 2002 Free Software Foundation, Inc. |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
235 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
236 Permission is granted to copy, distribute and/or modify this document |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
237 under the terms of the GNU Free Documentation License, Version 1.1 or |
42621
33aa22b1c9c0
Remove Preface from the `Invariant Section' listing of the License,
Robert J. Chassell <bob@rattlesnake.com>
parents:
42562
diff
changeset
|
238 any later version published by the Free Software Foundation; there |
33aa22b1c9c0
Remove Preface from the `Invariant Section' listing of the License,
Robert J. Chassell <bob@rattlesnake.com>
parents:
42562
diff
changeset
|
239 being no Invariant Section, with the Front-Cover Texts being ``A GNU |
33aa22b1c9c0
Remove Preface from the `Invariant Section' listing of the License,
Robert J. Chassell <bob@rattlesnake.com>
parents:
42562
diff
changeset
|
240 Manual'', and with the Back-Cover Texts as in (a) below. A copy of |
33aa22b1c9c0
Remove Preface from the `Invariant Section' listing of the License,
Robert J. Chassell <bob@rattlesnake.com>
parents:
42562
diff
changeset
|
241 the license is included in the section entitled ``GNU Free |
42562
fb149efd0c72
Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents:
42506
diff
changeset
|
242 Documentation License''. |
fb149efd0c72
Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents:
42506
diff
changeset
|
243 |
fb149efd0c72
Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents:
42506
diff
changeset
|
244 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and |
fb149efd0c72
Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents:
42506
diff
changeset
|
245 modify this GNU Manual, like GNU software. Copies published by the |
fb149efd0c72
Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents:
42506
diff
changeset
|
246 Free Software Foundation raise funds for GNU development.'' |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
247 @end ifinfo |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
248 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
249 @c half title; two lines here, so do not use `shorttitlepage' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
250 @tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
251 {\begingroup% |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
252 \hbox{}\vskip 1.5in \chaprm \centerline{An Introduction to}% |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
253 \endgroup}% |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
254 {\begingroup\hbox{}\vskip 0.25in \chaprm% |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
255 \centerline{Programming in Emacs Lisp}% |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
256 \endgroup\page\hbox{}\page} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
257 @end tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
258 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
259 @titlepage |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
260 @sp 6 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
261 @center @titlefont{An Introduction to} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
262 @sp 2 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
263 @center @titlefont{Programming in Emacs Lisp} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
264 @sp 2 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
265 @center Second Edition |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
266 @sp 4 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
267 @center by Robert J. Chassell |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
268 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
269 @page |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
270 @vskip 0pt plus 1filll |
42562
fb149efd0c72
Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents:
42506
diff
changeset
|
271 Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1997, 2001, 2002 Free Software Foundation, Inc. |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
272 @sp 2 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
273 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
274 Published by the Free Software Foundation, Inc.@* |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
275 59 Temple Place, Suite 330@* |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
276 Boston, MA 02111-1307 USA@* |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
277 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
278 Edition @value{edition-number}, @value{update-date} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
279 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
280 @c Printed copies are available for $20 each.@* |
42633
c0f9dbfc8232
Nitpicking change of format from ISBN-1882114-43-4 to ISBN 1-882114-43-4
Robert J. Chassell <bob@rattlesnake.com>
parents:
42632
diff
changeset
|
281 ISBN 1-882114-43-4 |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
282 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
283 Permission is granted to copy, distribute and/or modify this document |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
284 under the terms of the GNU Free Documentation License, Version 1.1 or |
42621
33aa22b1c9c0
Remove Preface from the `Invariant Section' listing of the License,
Robert J. Chassell <bob@rattlesnake.com>
parents:
42562
diff
changeset
|
285 any later version published by the Free Software Foundation; there |
33aa22b1c9c0
Remove Preface from the `Invariant Section' listing of the License,
Robert J. Chassell <bob@rattlesnake.com>
parents:
42562
diff
changeset
|
286 being no Invariant Section, with the Front-Cover Texts being ``A GNU |
33aa22b1c9c0
Remove Preface from the `Invariant Section' listing of the License,
Robert J. Chassell <bob@rattlesnake.com>
parents:
42562
diff
changeset
|
287 Manual'', and with the Back-Cover Texts as in (a) below. A copy of |
33aa22b1c9c0
Remove Preface from the `Invariant Section' listing of the License,
Robert J. Chassell <bob@rattlesnake.com>
parents:
42562
diff
changeset
|
288 the license is included in the section entitled ``GNU Free |
42562
fb149efd0c72
Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents:
42506
diff
changeset
|
289 Documentation License''. |
fb149efd0c72
Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents:
42506
diff
changeset
|
290 |
fb149efd0c72
Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents:
42506
diff
changeset
|
291 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and |
fb149efd0c72
Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents:
42506
diff
changeset
|
292 modify this GNU Manual, like GNU software. Copies published by the |
fb149efd0c72
Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents:
42506
diff
changeset
|
293 Free Software Foundation raise funds for GNU development.'' |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
294 @end titlepage |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
295 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
296 @iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
297 @headings off |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
298 @evenheading @thispage @| @| @thischapter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
299 @oddheading @thissection @| @| @thispage |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
300 @end iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
301 |
41499
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
302 @ifnothtml |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
303 |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
304 @c Keep T.O.C. short by tightening up. |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
305 @ifset largebook |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
306 @tex |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
307 \global\parskip 2pt plus 1pt |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
308 \global\advance\baselineskip by -1pt |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
309 @end tex |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
310 @end ifset |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
311 |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
312 @shortcontents |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
313 @contents |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
314 |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
315 @ifset largebook |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
316 @tex |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
317 \global\parskip 6pt plus 1pt |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
318 \global\advance\baselineskip by 1pt |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
319 @end tex |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
320 @end ifset |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
321 |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
322 @end ifnothtml |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
323 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
324 @c >>>> Set pageno appropriately <<<< |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
325 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
326 @c The first page of the Preface is a roman numeral; it is the first |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
327 @c right handed page after the Table of Contents; hence the following |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
328 @c setting must be for an odd negative number. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
329 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
330 @c if largebook, there are 8 pages in Table of Contents |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
331 @ifset largebook |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
332 @iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
333 @pageno = -9 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
334 @end iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
335 @end ifset |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
336 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
337 @c if smallbook, there are 10 pages in Table of Contents |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
338 @ifclear largebook |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
339 @iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
340 @pageno = -11 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
341 @end iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
342 @end ifclear |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
343 |
41499
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
344 @ifnottex |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
345 @node Top, Preface, (dir), (dir) |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
346 @top An Introduction to Programming in Emacs Lisp |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
347 |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
348 This is an introduction to @cite{Programming in Emacs Lisp}, for |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
349 people who are not programmers. |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
350 |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
351 This master menu first lists each chapter and index; then it lists |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
352 every node in every chapter. |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
353 @end ifnottex |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
354 |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
355 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
356 * Preface:: What to look for. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
357 * List Processing:: What is Lisp? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
358 * Practicing Evaluation:: Running several programs. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
359 * Writing Defuns:: How to write function definitions. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
360 * Buffer Walk Through:: Exploring a few buffer-related functions. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
361 * More Complex:: A few, even more complex functions. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
362 * Narrowing & Widening:: Restricting your and Emacs attention to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
363 a region. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
364 * car cdr & cons:: Fundamental functions in Lisp. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
365 * Cutting & Storing Text:: Removing text and saving it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
366 * List Implementation:: How lists are implemented in the computer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
367 * Yanking:: Pasting stored text. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
368 * Loops & Recursion:: How to repeat a process. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
369 * Regexp Search:: Regular expression searches. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
370 * Counting Words:: A review of repetition and regexps. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
371 * Words in a defun:: Counting words in a @code{defun}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
372 * Readying a Graph:: A prototype graph printing function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
373 * Emacs Initialization:: How to write a @file{.emacs} file. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
374 * Debugging:: How to run the Emacs Lisp debuggers. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
375 * Conclusion:: Now you have the basics. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
376 * the-the:: An appendix: how to find reduplicated words. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
377 * Kill Ring:: An appendix: how the kill ring works. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
378 * Full Graph:: How to create a graph with labelled axes. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
379 * GNU Free Documentation License:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
380 * Index:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
381 * About the Author:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
382 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
383 @detailmenu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
384 --- The Detailed Node Listing --- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
385 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
386 Preface |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
387 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
388 * Why:: Why learn Emacs Lisp? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
389 * On Reading this Text:: Read, gain familiarity, pick up habits.... |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
390 * Who You Are:: For whom this is written. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
391 * Lisp History:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
392 * Note for Novices:: You can read this as a novice. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
393 * Thank You:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
394 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
395 List Processing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
396 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
397 * Lisp Lists:: What are lists? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
398 * Run a Program:: Any list in Lisp is a program ready to run. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
399 * Making Errors:: Generating an error message. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
400 * Names & Definitions:: Names of symbols and function definitions. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
401 * Lisp Interpreter:: What the Lisp interpreter does. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
402 * Evaluation:: Running a program. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
403 * Variables:: Returning a value from a variable. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
404 * Arguments:: Passing information to a function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
405 * set & setq:: Setting the value of a variable. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
406 * Summary:: The major points. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
407 * Error Message Exercises:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
408 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
409 Lisp Lists |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
410 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
411 * Numbers Lists:: List have numbers, other lists, in them. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
412 * Lisp Atoms:: Elemental entities. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
413 * Whitespace in Lists:: Formating lists to be readable. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
414 * Typing Lists:: How GNU Emacs helps you type lists. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
415 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
416 The Lisp Interpreter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
417 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
418 * Complications:: Variables, Special forms, Lists within. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
419 * Byte Compiling:: Specially processing code for speed. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
420 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
421 Evaluation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
422 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
423 * Evaluating Inner Lists:: Lists within lists... |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
424 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
425 Variables |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
426 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
427 * fill-column Example:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
428 * Void Function:: The error message for a symbol |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
429 without a function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
430 * Void Variable:: The error message for a symbol without a value. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
431 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
432 Arguments |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
433 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
434 * Data types:: Types of data passed to a function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
435 * Args as Variable or List:: An argument can be the value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
436 of a variable or list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
437 * Variable Number of Arguments:: Some functions may take a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
438 variable number of arguments. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
439 * Wrong Type of Argument:: Passing an argument of the wrong type |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
440 to a function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
441 * message:: A useful function for sending messages. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
442 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
443 Setting the Value of a Variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
444 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
445 * Using set:: Setting values. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
446 * Using setq:: Setting a quoted value. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
447 * Counting:: Using @code{setq} to count. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
448 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
449 Practicing Evaluation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
450 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
451 * How to Evaluate:: Typing editing commands or @kbd{C-x C-e} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
452 causes evaluation. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
453 * Buffer Names:: Buffers and files are different. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
454 * Getting Buffers:: Getting a buffer itself, not merely its name. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
455 * Switching Buffers:: How to change to another buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
456 * Buffer Size & Locations:: Where point is located and the size of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
457 the buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
458 * Evaluation Exercise:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
459 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
460 How To Write Function Definitions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
461 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
462 * Primitive Functions:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
463 * defun:: The @code{defun} special form. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
464 * Install:: Install a function definition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
465 * Interactive:: Making a function interactive. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
466 * Interactive Options:: Different options for @code{interactive}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
467 * Permanent Installation:: Installing code permanently. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
468 * let:: Creating and initializing local variables. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
469 * if:: What if? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
470 * else:: If--then--else expressions. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
471 * Truth & Falsehood:: What Lisp considers false and true. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
472 * save-excursion:: Keeping track of point, mark, and buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
473 * Review:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
474 * defun Exercises:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
475 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
476 Install a Function Definition |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
477 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
478 * Effect of installation:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
479 * Change a defun:: How to change a function definition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
480 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
481 Make a Function Interactive |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
482 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
483 * Interactive multiply-by-seven:: An overview. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
484 * multiply-by-seven in detail:: The interactive version. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
485 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
486 @code{let} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
487 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
488 * Prevent confusion:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
489 * Parts of let Expression:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
490 * Sample let Expression:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
491 * Uninitialized let Variables:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
492 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
493 The @code{if} Special Form |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
494 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
495 * if in more detail:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
496 * type-of-animal in detail:: An example of an @code{if} expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
497 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
498 Truth and Falsehood in Emacs Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
499 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
500 * nil explained:: @code{nil} has two meanings. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
501 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
502 @code{save-excursion} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
503 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
504 * Point and mark:: A review of various locations. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
505 * Template for save-excursion:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
506 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
507 A Few Buffer--Related Functions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
508 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
509 * Finding More:: How to find more information. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
510 * simplified-beginning-of-buffer:: Shows @code{goto-char}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
511 @code{point-min}, and @code{push-mark}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
512 * mark-whole-buffer:: Almost the same as @code{beginning-of-buffer}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
513 * append-to-buffer:: Uses @code{save-excursion} and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
514 @code{insert-buffer-substring}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
515 * Buffer Related Review:: Review. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
516 * Buffer Exercises:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
517 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
518 The Definition of @code{mark-whole-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
519 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
520 * mark-whole-buffer overview:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
521 * Body of mark-whole-buffer:: Only three lines of code. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
522 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
523 The Definition of @code{append-to-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
524 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
525 * append-to-buffer overview:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
526 * append interactive:: A two part interactive expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
527 * append-to-buffer body:: Incorporates a @code{let} expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
528 * append save-excursion:: How the @code{save-excursion} works. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
529 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
530 A Few More Complex Functions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
531 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
532 * copy-to-buffer:: With @code{set-buffer}, @code{get-buffer-create}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
533 * insert-buffer:: Read-only, and with @code{or}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
534 * beginning-of-buffer:: Shows @code{goto-char}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
535 @code{point-min}, and @code{push-mark}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
536 * Second Buffer Related Review:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
537 * optional Exercise:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
538 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
539 The Definition of @code{insert-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
540 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
541 * insert-buffer code:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
542 * insert-buffer interactive:: When you can read, but not write. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
543 * insert-buffer body:: The body has an @code{or} and a @code{let}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
544 * if & or:: Using an @code{if} instead of an @code{or}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
545 * Insert or:: How the @code{or} expression works. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
546 * Insert let:: Two @code{save-excursion} expressions. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
547 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
548 The Interactive Expression in @code{insert-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
549 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
550 * Read-only buffer:: When a buffer cannot be modified. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
551 * b for interactive:: An existing buffer or else its name. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
552 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
553 Complete Definition of @code{beginning-of-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
554 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
555 * Optional Arguments:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
556 * beginning-of-buffer opt arg:: Example with optional argument. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
557 * beginning-of-buffer complete:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
558 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
559 @code{beginning-of-buffer} with an Argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
560 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
561 * Disentangle beginning-of-buffer:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
562 * Large buffer case:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
563 * Small buffer case:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
564 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
565 Narrowing and Widening |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
566 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
567 * Narrowing advantages:: The advantages of narrowing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
568 * save-restriction:: The @code{save-restriction} special form. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
569 * what-line:: The number of the line that point is on. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
570 * narrow Exercise:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
571 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
572 @code{car}, @code{cdr}, @code{cons}: Fundamental Functions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
573 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
574 * Strange Names:: An historical aside: why the strange names? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
575 * car & cdr:: Functions for extracting part of a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
576 * cons:: Constructing a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
577 * nthcdr:: Calling @code{cdr} repeatedly. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
578 * nth:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
579 * setcar:: Changing the first element of a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
580 * setcdr:: Changing the rest of a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
581 * cons Exercise:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
582 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
583 @code{cons} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
584 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
585 * Build a list:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
586 * length:: How to find the length of a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
587 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
588 Cutting and Storing Text |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
589 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
590 * Storing Text:: Text is stored in a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
591 * zap-to-char:: Cutting out text up to a character. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
592 * kill-region:: Cutting text out of a region. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
593 * Digression into C:: Minor note on C programming language macros. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
594 * defvar:: How to give a variable an initial value. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
595 * copy-region-as-kill:: A definition for copying text. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
596 * cons & search-fwd Review:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
597 * search Exercises:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
598 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
599 @code{zap-to-char} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
600 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
601 * Complete zap-to-char:: The complete implementation. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
602 * zap-to-char interactive:: A three part interactive expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
603 * zap-to-char body:: A short overview. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
604 * search-forward:: How to search for a string. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
605 * progn:: The @code{progn} special form. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
606 * Summing up zap-to-char:: Using @code{point} and @code{search-forward}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
607 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
608 @code{kill-region} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
609 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
610 * Complete kill-region:: The function definition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
611 * condition-case:: Dealing with a problem. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
612 * delete-and-extract-region:: Doing the work. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
613 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
614 Initializing a Variable with @code{defvar} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
615 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
616 * See variable current value:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
617 * defvar and asterisk:: An old-time convention. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
618 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
619 @code{copy-region-as-kill} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
620 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
621 * Complete copy-region-as-kill:: The complete function definition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
622 * copy-region-as-kill body:: The body of @code{copy-region-as-kill}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
623 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
624 The Body of @code{copy-region-as-kill} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
625 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
626 * last-command & this-command:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
627 * kill-append function:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
628 * kill-new function:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
629 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
630 How Lists are Implemented |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
631 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
632 * Lists diagrammed:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
633 * Symbols as Chest:: Exploring a powerful metaphor. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
634 * List Exercise:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
635 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
636 Yanking Text Back |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
637 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
638 * Kill Ring Overview:: The kill ring is a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
639 * kill-ring-yank-pointer:: The @code{kill-ring-yank-pointer} variable. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
640 * yank nthcdr Exercises:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
641 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
642 Loops and Recursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
643 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
644 * while:: Causing a stretch of code to repeat. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
645 * dolist dotimes:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
646 * Recursion:: Causing a function to call itself. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
647 * Looping exercise:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
648 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
649 @code{while} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
650 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
651 * Looping with while:: Repeat so long as test returns true. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
652 * Loop Example:: A @code{while} loop that uses a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
653 * print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
654 * Incrementing Loop:: A loop with an incrementing counter. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
655 * Decrementing Loop:: A loop with a decrementing counter. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
656 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
657 A Loop with an Incrementing Counter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
658 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
659 * Incrementing Example:: Counting pebbles in a triangle. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
660 * Inc Example parts:: The parts of the function definition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
661 * Inc Example altogether:: Putting the function definition together. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
662 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
663 Loop with a Decrementing Counter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
664 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
665 * Decrementing Example:: More pebbles on the beach. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
666 * Dec Example parts:: The parts of the function definition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
667 * Dec Example altogether:: Putting the function definition together. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
668 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
669 Save your time: @code{dolist} and @code{dotimes} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
670 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
671 * dolist:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
672 * dotimes:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
673 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
674 Recursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
675 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
676 * Building Robots:: Same model, different serial number ... |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
677 * Recursive Definition Parts:: Walk until you stop ... |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
678 * Recursion with list:: Using a list as the test whether to recurse. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
679 * Recursive triangle function:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
680 * Recursion with cond:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
681 * Recursive Patterns:: Often used templates. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
682 * No Deferment:: Don't store up work ... |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
683 * No deferment solution:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
684 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
685 Recursion in Place of a Counter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
686 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
687 * Recursive Example arg of 1 or 2:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
688 * Recursive Example arg of 3 or 4:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
689 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
690 Recursive Patterns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
691 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
692 * Every:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
693 * Accumulate:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
694 * Keep:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
695 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
696 Regular Expression Searches |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
697 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
698 * sentence-end:: The regular expression for @code{sentence-end}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
699 * re-search-forward:: Very similar to @code{search-forward}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
700 * forward-sentence:: A straightforward example of regexp search. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
701 * forward-paragraph:: A somewhat complex example. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
702 * etags:: How to create your own @file{TAGS} table. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
703 * Regexp Review:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
704 * re-search Exercises:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
705 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
706 @code{forward-sentence} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
707 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
708 * Complete forward-sentence:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
709 * fwd-sentence while loops:: Two @code{while} loops. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
710 * fwd-sentence re-search:: A regular expression search. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
711 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
712 @code{forward-paragraph}: a Goldmine of Functions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
713 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
714 * forward-paragraph in brief:: Key parts of the function definition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
715 * fwd-para let:: The @code{let*} expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
716 * fwd-para while:: The forward motion @code{while} loop. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
717 * fwd-para between paragraphs:: Movement between paragraphs. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
718 * fwd-para within paragraph:: Movement within paragraphs. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
719 * fwd-para no fill prefix:: When there is no fill prefix. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
720 * fwd-para with fill prefix:: When there is a fill prefix. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
721 * fwd-para summary:: Summary of @code{forward-paragraph} code. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
722 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
723 Counting: Repetition and Regexps |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
724 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
725 * Why Count Words:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
726 * count-words-region:: Use a regexp, but find a problem. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
727 * recursive-count-words:: Start with case of no words in region. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
728 * Counting Exercise:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
729 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
730 The @code{count-words-region} Function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
731 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
732 * Design count-words-region:: The definition using a @code{while} loop. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
733 * Whitespace Bug:: The Whitespace Bug in @code{count-words-region}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
734 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
735 Counting Words in a @code{defun} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
736 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
737 * Divide and Conquer:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
738 * Words and Symbols:: What to count? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
739 * Syntax:: What constitutes a word or symbol? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
740 * count-words-in-defun:: Very like @code{count-words}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
741 * Several defuns:: Counting several defuns in a file. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
742 * Find a File:: Do you want to look at a file? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
743 * lengths-list-file:: A list of the lengths of many definitions. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
744 * Several files:: Counting in definitions in different files. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
745 * Several files recursively:: Recursively counting in different files. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
746 * Prepare the data:: Prepare the data for display in a graph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
747 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
748 Count Words in @code{defuns} in Different Files |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
749 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
750 * lengths-list-many-files:: Return a list of the lengths of defuns. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
751 * append:: Attach one list to another. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
752 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
753 Prepare the Data for Display in a Graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
754 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
755 * Sorting:: Sorting lists. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
756 * Files List:: Making a list of files. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
757 * Counting function definitions:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
758 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
759 Readying a Graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
760 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
761 * Columns of a graph:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
762 * graph-body-print:: How to print the body of a graph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
763 * recursive-graph-body-print:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
764 * Printed Axes:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
765 * Line Graph Exercise:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
766 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
767 Your @file{.emacs} File |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
768 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
769 * Default Configuration:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
770 * Site-wide Init:: You can write site-wide init files. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
771 * defcustom:: Emacs will write code for you. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
772 * Beginning a .emacs File:: How to write a @code{.emacs file}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
773 * Text and Auto-fill:: Automatically wrap lines. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
774 * Mail Aliases:: Use abbreviations for email addresses. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
775 * Indent Tabs Mode:: Don't use tabs with @TeX{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
776 * Keybindings:: Create some personal keybindings. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
777 * Keymaps:: More about key binding. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
778 * Loading Files:: Load (i.e., evaluate) files automatically. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
779 * Autoload:: Make functions available. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
780 * Simple Extension:: Define a function; bind it to a key. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
781 * X11 Colors:: Colors in version 19 in X. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
782 * Miscellaneous:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
783 * Mode Line:: How to customize your mode line. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
784 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
785 Debugging |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
786 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
787 * debug:: How to use the built-in debugger. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
788 * debug-on-entry:: Start debugging when you call a function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
789 * debug-on-quit:: Start debugging when you quit with @kbd{C-g}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
790 * edebug:: How to use Edebug, a source level debugger. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
791 * Debugging Exercises:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
792 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
793 Handling the Kill Ring |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
794 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
795 * rotate-yank-pointer:: Move a pointer along a list and around. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
796 * yank:: Paste a copy of a clipped element. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
797 * yank-pop:: Insert first element pointed to. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
798 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
799 The @code{rotate-yank-pointer} Function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
801 * Understanding rotate-yk-ptr:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
802 * rotate-yk-ptr body:: The body of @code{rotate-yank-pointer}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
803 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
804 The Body of @code{rotate-yank-pointer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
805 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
806 * Digression concerning error:: How to mislead humans, but not computers. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
807 * rotate-yk-ptr else-part:: The else-part of the @code{if} expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
808 * Remainder Function:: The remainder, @code{%}, function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
809 * rotate-yk-ptr remainder:: Using @code{%} in @code{rotate-yank-pointer}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
810 * kill-rng-yk-ptr last elt:: Pointing to the last element. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
811 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
812 @code{yank} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
813 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
814 * rotate-yk-ptr arg:: Pass the argument to @code{rotate-yank-pointer}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
815 * rotate-yk-ptr negative arg:: Pass a negative argument. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
816 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
817 A Graph with Labelled Axes |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
818 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
819 * Labelled Example:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
820 * print-graph Varlist:: @code{let} expression in @code{print-graph}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
821 * print-Y-axis:: Print a label for the vertical axis. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
822 * print-X-axis:: Print a horizontal label. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
823 * Print Whole Graph:: The function to print a complete graph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
824 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
825 The @code{print-Y-axis} Function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
826 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
827 * Height of label:: What height for the Y axis? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
828 * Compute a Remainder:: How to compute the remainder of a division. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
829 * Y Axis Element:: Construct a line for the Y axis. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
830 * Y-axis-column:: Generate a list of Y axis labels. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
831 * print-Y-axis Penultimate:: A not quite final version. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
832 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
833 The @code{print-X-axis} Function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
834 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
835 * Similarities differences:: Much like @code{print-Y-axis}, but not exactly. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
836 * X Axis Tic Marks:: Create tic marks for the horizontal axis. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
837 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
838 Printing the Whole Graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
839 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
840 * The final version:: A few changes. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
841 * Test print-graph:: Run a short test. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
842 * Graphing words in defuns:: Executing the final code. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
843 * lambda:: How to write an anonymous function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
844 * mapcar:: Apply a function to elements of a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
845 * Another Bug:: Yet another bug @dots{} most insidious. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
846 * Final printed graph:: The graph itself! |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
847 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
848 @end detailmenu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
849 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
850 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
851 @node Preface, List Processing, Top, Top |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
852 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
853 @unnumbered Preface |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
854 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
855 Most of the GNU Emacs integrated environment is written in the programming |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
856 language called Emacs Lisp. The code written in this programming |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
857 language is the software---the sets of instructions---that tell the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
858 computer what to do when you give it commands. Emacs is designed so |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
859 that you can write new code in Emacs Lisp and easily install it as an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
860 extension to the editor. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
861 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
862 (GNU Emacs is sometimes called an ``extensible editor'', but it does |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
863 much more than provide editing capabilities. It is better to refer to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
864 Emacs as an ``extensible computing environment''. However, that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
865 phrase is quite a mouthful. It is easier to refer to Emacs simply as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
866 an editor. Moreover, everything you do in Emacs---find the Mayan date |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
867 and phases of the moon, simplify polynomials, debug code, manage |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
868 files, read letters, write books---all these activities are kinds of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
869 editing in the most general sense of the word.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
870 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
871 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
872 * Why:: Why learn Emacs Lisp? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
873 * On Reading this Text:: Read, gain familiarity, pick up habits.... |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
874 * Who You Are:: For whom this is written. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
875 * Lisp History:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
876 * Note for Novices:: You can read this as a novice. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
877 * Thank You:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
878 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
879 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
880 @node Why, On Reading this Text, Preface, Preface |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
881 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
882 @unnumberedsec Why Study Emacs Lisp? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
883 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
884 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
885 Although Emacs Lisp is usually thought of in association only with Emacs, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
886 it is a full computer programming language. You can use Emacs Lisp as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
887 you would any other programming language. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
888 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
889 Perhaps you want to understand programming; perhaps you want to extend |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
890 Emacs; or perhaps you want to become a programmer. This introduction to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
891 Emacs Lisp is designed to get you started: to guide you in learning the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
892 fundamentals of programming, and more importantly, to show you how you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
893 can teach yourself to go further. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
894 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
895 @node On Reading this Text, Who You Are, Why, Preface |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
896 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
897 @unnumberedsec On Reading this Text |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
898 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
899 All through this document, you will see little sample programs you can |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
900 run inside of Emacs. If you read this document in Info inside of GNU |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
901 Emacs, you can run the programs as they appear. (This is easy to do and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
902 is explained when the examples are presented.) Alternatively, you can |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
903 read this introduction as a printed book while sitting beside a computer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
904 running Emacs. (This is what I like to do; I like printed books.) If |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
905 you don't have a running Emacs beside you, you can still read this book, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
906 but in this case, it is best to treat it as a novel or as a travel guide |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
907 to a country not yet visited: interesting, but not the same as being |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
908 there. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
909 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
910 Much of this introduction is dedicated to walk-throughs or guided tours |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
911 of code used in GNU Emacs. These tours are designed for two purposes: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
912 first, to give you familiarity with real, working code (code you use |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
913 every day); and, second, to give you familiarity with the way Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
914 works. It is interesting to see how a working environment is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
915 implemented. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
916 Also, I |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
917 hope that you will pick up the habit of browsing through source code. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
918 You can learn from it and mine it for ideas. Having GNU Emacs is like |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
919 having a dragon's cave of treasures. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
920 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
921 In addition to learning about Emacs as an editor and Emacs Lisp as a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
922 programming language, the examples and guided tours will give you an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
923 opportunity to get acquainted with Emacs as a Lisp programming |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
924 environment. GNU Emacs supports programming and provides tools that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
925 you will want to become comfortable using, such as @kbd{M-.} (the key |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
926 which invokes the @code{find-tag} command). You will also learn about |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
927 buffers and other objects that are part of the environment. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
928 Learning about these features of Emacs is like learning new routes |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
929 around your home town. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
930 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
931 @ignore |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
932 In addition, I have written several programs as extended examples. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
933 Although these are examples, the programs are real. I use them. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
934 Other people use them. You may use them. Beyond the fragments of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
935 programs used for illustrations, there is very little in here that is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
936 `just for teaching purposes'; what you see is used. This is a great |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
937 advantage of Emacs Lisp: it is easy to learn to use it for work. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
938 @end ignore |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
939 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
940 Finally, I hope to convey some of the skills for using Emacs to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
941 learn aspects of programming that you don't know. You can often use |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
942 Emacs to help you understand what puzzles you or to find out how to do |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
943 something new. This self-reliance is not only a pleasure, but an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
944 advantage. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
945 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
946 @node Who You Are, Lisp History, On Reading this Text, Preface |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
947 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
948 @unnumberedsec For Whom This is Written |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
949 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
950 This text is written as an elementary introduction for people who are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
951 not programmers. If you are a programmer, you may not be satisfied with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
952 this primer. The reason is that you may have become expert at reading |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
953 reference manuals and be put off by the way this text is organized. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
954 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
955 An expert programmer who reviewed this text said to me: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
956 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
957 @quotation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
958 @i{I prefer to learn from reference manuals. I ``dive into'' each |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
959 paragraph, and ``come up for air'' between paragraphs.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
960 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
961 @i{When I get to the end of a paragraph, I assume that that subject is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
962 done, finished, that I know everything I need (with the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
963 possible exception of the case when the next paragraph starts talking |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
964 about it in more detail). I expect that a well written reference manual |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
965 will not have a lot of redundancy, and that it will have excellent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
966 pointers to the (one) place where the information I want is.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
967 @end quotation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
968 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
969 This introduction is not written for this person! |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
970 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
971 Firstly, I try to say everything at least three times: first, to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
972 introduce it; second, to show it in context; and third, to show it in a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
973 different context, or to review it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
974 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
975 Secondly, I hardly ever put all the information about a subject in one |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
976 place, much less in one paragraph. To my way of thinking, that imposes |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
977 too heavy a burden on the reader. Instead I try to explain only what |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
978 you need to know at the time. (Sometimes I include a little extra |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
979 information so you won't be surprised later when the additional |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
980 information is formally introduced.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
981 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
982 When you read this text, you are not expected to learn everything the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
983 first time. Frequently, you need only make, as it were, a `nodding |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
984 acquaintance' with some of the items mentioned. My hope is that I have |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
985 structured the text and given you enough hints that you will be alert to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
986 what is important, and concentrate on it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
987 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
988 You will need to ``dive into'' some paragraphs; there is no other way |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
989 to read them. But I have tried to keep down the number of such |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
990 paragraphs. This book is intended as an approachable hill, rather than |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
991 as a daunting mountain. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
992 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
993 This introduction to @cite{Programming in Emacs Lisp} has a companion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
994 document, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
995 @iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
996 @cite{The GNU Emacs Lisp Reference Manual}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
997 @end iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
998 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
999 @ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1000 Emacs Lisp Reference Manual}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1001 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1002 The reference manual has more detail than this introduction. In the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1003 reference manual, all the information about one topic is concentrated |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1004 in one place. You should turn to it if you are like the programmer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1005 quoted above. And, of course, after you have read this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1006 @cite{Introduction}, you will find the @cite{Reference Manual} useful |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1007 when you are writing your own programs. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1008 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1009 @node Lisp History, Note for Novices, Who You Are, Preface |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1010 @unnumberedsec Lisp History |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1011 @cindex Lisp history |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1012 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1013 Lisp was first developed in the late 1950s at the Massachusetts |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1014 Institute of Technology for research in artificial intelligence. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1015 great power of the Lisp language makes it superior for other purposes as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1016 well, such as writing editor commands and integrated environments. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1017 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1018 @cindex Maclisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1019 @cindex Common Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1020 GNU Emacs Lisp is largely inspired by Maclisp, which was written at MIT |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1021 in the 1960s. It is somewhat inspired by Common Lisp, which became a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1022 standard in the 1980s. However, Emacs Lisp is much simpler than Common |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1023 Lisp. (The standard Emacs distribution contains an optional extensions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1024 file, @file{cl.el}, that adds many Common Lisp features to Emacs Lisp.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1025 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1026 @node Note for Novices, Thank You, Lisp History, Preface |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1027 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1028 @unnumberedsec A Note for Novices |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1029 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1030 If you don't know GNU Emacs, you can still read this document |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1031 profitably. However, I recommend you learn Emacs, if only to learn to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1032 move around your computer screen. You can teach yourself how to use |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1033 Emacs with the on-line tutorial. To use it, type @kbd{C-h t}. (This |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1034 means you press and release the @key{CTRL} key and the @kbd{h} at the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1035 same time, and then press and release @kbd{t}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1036 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1037 Also, I often refer to one of Emacs' standard commands by listing the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1038 keys which you press to invoke the command and then giving the name of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1039 the command in parentheses, like this: @kbd{M-C-\} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1040 (@code{indent-region}). What this means is that the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1041 @code{indent-region} command is customarily invoked by typing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1042 @kbd{M-C-\}. (You can, if you wish, change the keys that are typed to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1043 invoke the command; this is called @dfn{rebinding}. @xref{Keymaps, , |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1044 Keymaps}.) The abbreviation @kbd{M-C-\} means that you type your |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1045 @key{META} key, @key{CTRL} key and @key{\} key all at the same time. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1046 (On many modern keyboards the @key{META} key is labelled |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1047 @key{ALT}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1048 Sometimes a combination like this is called a keychord, since it is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1049 similar to the way you play a chord on a piano. If your keyboard does |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1050 not have a @key{META} key, the @key{ESC} key prefix is used in place |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1051 of it. In this case, @kbd{M-C-\} means that you press and release your |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1052 @key{ESC} key and then type the @key{CTRL} key and the @key{\} key at |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1053 the same time. But usually @kbd{M-C-\} means press the @key{CTRL} key |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1054 along with the key that is labelled @key{ALT} and, at the same time, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1055 press the @key{\} key. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1056 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1057 In addition to typing a lone keychord, you can prefix what you type |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1058 with @kbd{C-u}, which is called the `universal argument'. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1059 @kbd{C-u} keychord passes an argument to the subsequent command. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1060 Thus, to indent a region of plain text by 6 spaces, mark the region, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1061 and then type @w{@kbd{C-u 6 M-C-\}}. (If you do not specify a number, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1062 Emacs either passes the number 4 to the command or otherwise runs the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1063 command differently than it would otherwise.) @xref{Arguments, , |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1064 Numeric Arguments, emacs, The GNU Emacs Manual}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1065 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1066 If you are reading this in Info using GNU Emacs, you can read through |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1067 this whole document just by pressing the space bar, @key{SPC}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1068 (To learn about Info, type @kbd{C-h i} and then select Info.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1069 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1070 A note on terminology: when I use the word Lisp alone, I often am |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1071 referring to the various dialects of Lisp in general, but when I speak |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1072 of Emacs Lisp, I am referring to GNU Emacs Lisp in particular. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1073 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1074 @node Thank You, , Note for Novices, Preface |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1075 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1076 @unnumberedsec Thank You |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1077 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1078 My thanks to all who helped me with this book. My especial thanks to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1079 @r{Jim Blandy}, @r{Noah Friedman}, @w{Jim Kingdon}, @r{Roland |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1080 McGrath}, @w{Frank Ritter}, @w{Randy Smith}, @w{Richard M.@: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1081 Stallman}, and @w{Melissa Weisshaus}. My thanks also go to both |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1082 @w{Philip Johnson} and @w{David Stampe} for their patient |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1083 encouragement. My mistakes are my own. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1084 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1085 @flushright |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1086 Robert J. Chassell |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1087 @end flushright |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1088 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1089 @c ================ Beginning of main text ================ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1090 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1091 @c Start main text on right-hand (verso) page |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1092 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1093 @tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1094 \par\vfill\supereject |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1095 \headings off |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1096 \ifodd\pageno |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1097 \par\vfill\supereject |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1098 \else |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1099 \par\vfill\supereject |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1100 \page\hbox{}\page |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1101 \par\vfill\supereject |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1102 \fi |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1103 @end tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1104 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1105 @iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1106 @headings off |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1107 @evenheading @thispage @| @| @thischapter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1108 @oddheading @thissection @| @| @thispage |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1109 @pageno = 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1110 @end iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1111 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1112 @node List Processing, Practicing Evaluation, Preface, Top |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1113 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1114 @chapter List Processing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1115 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1116 To the untutored eye, Lisp is a strange programming language. In Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1117 code there are parentheses everywhere. Some people even claim that the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1118 name stands for `Lots of Isolated Silly Parentheses'. But the claim is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1119 unwarranted. Lisp stands for LISt Processing, and the programming |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1120 language handles @emph{lists} (and lists of lists) by putting them |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1121 between parentheses. The parentheses mark the boundaries of the list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1122 Sometimes a list is preceded by a single apostrophe or quotation mark, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1123 @samp{'}. Lists are the basis of Lisp. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1124 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1125 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1126 * Lisp Lists:: What are lists? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1127 * Run a Program:: Any list in Lisp is a program ready to run. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1128 * Making Errors:: Generating an error message. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1129 * Names & Definitions:: Names of symbols and function definitions. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1130 * Lisp Interpreter:: What the Lisp interpreter does. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1131 * Evaluation:: Running a program. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1132 * Variables:: Returning a value from a variable. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1133 * Arguments:: Passing information to a function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1134 * set & setq:: Setting the value of a variable. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1135 * Summary:: The major points. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1136 * Error Message Exercises:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1137 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1138 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1139 @node Lisp Lists, Run a Program, List Processing, List Processing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1140 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1141 @section Lisp Lists |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1142 @cindex Lisp Lists |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1143 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1144 In Lisp, a list looks like this: @code{'(rose violet daisy buttercup)}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1145 This list is preceded by a single apostrophe. It could just as well be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1146 written as follows, which looks more like the kind of list you are likely |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1147 to be familiar with: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1148 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1149 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1150 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1151 '(rose |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1152 violet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1153 daisy |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1154 buttercup) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1155 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1156 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1157 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1158 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1159 The elements of this list are the names of the four different flowers, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1160 separated from each other by whitespace and surrounded by parentheses, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1161 like flowers in a field with a stone wall around them. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1162 @cindex Flowers in a field |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1163 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1164 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1165 * Numbers Lists:: List have numbers, other lists, in them. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1166 * Lisp Atoms:: Elemental entities. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1167 * Whitespace in Lists:: Formating lists to be readable. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1168 * Typing Lists:: How GNU Emacs helps you type lists. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1169 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1170 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1171 @node Numbers Lists, Lisp Atoms, Lisp Lists, Lisp Lists |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1172 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1173 @unnumberedsubsec Numbers, Lists inside of Lists |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1174 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1175 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1176 Lists can also have numbers in them, as in this list: @code{(+ 2 2)}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1177 This list has a plus-sign, @samp{+}, followed by two @samp{2}s, each |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1178 separated by whitespace. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1179 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1180 In Lisp, both data and programs are represented the same way; that is, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1181 they are both lists of words, numbers, or other lists, separated by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1182 whitespace and surrounded by parentheses. (Since a program looks like |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1183 data, one program may easily serve as data for another; this is a very |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1184 powerful feature of Lisp.) (Incidentally, these two parenthetical |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1185 remarks are @emph{not} Lisp lists, because they contain @samp{;} and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1186 @samp{.} as punctuation marks.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1187 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1188 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1189 Here is another list, this time with a list inside of it: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1190 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1191 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1192 '(this list has (a list inside of it)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1193 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1194 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1195 The components of this list are the words @samp{this}, @samp{list}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1196 @samp{has}, and the list @samp{(a list inside of it)}. The interior |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1197 list is made up of the words @samp{a}, @samp{list}, @samp{inside}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1198 @samp{of}, @samp{it}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1199 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1200 @node Lisp Atoms, Whitespace in Lists, Numbers Lists, Lisp Lists |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1201 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1202 @subsection Lisp Atoms |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1203 @cindex Lisp Atoms |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1204 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1205 In Lisp, what we have been calling words are called @dfn{atoms}. This |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1206 term comes from the historical meaning of the word atom, which means |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1207 `indivisible'. As far as Lisp is concerned, the words we have been |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1208 using in the lists cannot be divided into any smaller parts and still |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1209 mean the same thing as part of a program; likewise with numbers and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1210 single character symbols like @samp{+}. On the other hand, unlike an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1211 atom, a list can be split into parts. (@xref{car cdr & cons, , |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1212 @code{car} @code{cdr} & @code{cons} Fundamental Functions}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1213 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1214 In a list, atoms are separated from each other by whitespace. They can be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1215 right next to a parenthesis. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1216 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1217 @cindex @samp{empty list} defined |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1218 Technically speaking, a list in Lisp consists of parentheses surrounding |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1219 atoms separated by whitespace or surrounding other lists or surrounding |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1220 both atoms and other lists. A list can have just one atom in it or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1221 have nothing in it at all. A list with nothing in it looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1222 @code{()}, and is called the @dfn{empty list}. Unlike anything else, an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1223 empty list is considered both an atom and a list at the same time. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1224 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1225 @cindex Symbolic expressions, introduced |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1226 @cindex @samp{expression} defined |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1227 @cindex @samp{form} defined |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1228 The printed representation of both atoms and lists are called |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1229 @dfn{symbolic expressions} or, more concisely, @dfn{s-expressions}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1230 The word @dfn{expression} by itself can refer to either the printed |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1231 representation, or to the atom or list as it is held internally in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1232 computer. Often, people use the term @dfn{expression} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1233 indiscriminately. (Also, in many texts, the word @dfn{form} is used |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1234 as a synonym for expression.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1235 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1236 Incidentally, the atoms that make up our universe were named such when |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1237 they were thought to be indivisible; but it has been found that physical |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1238 atoms are not indivisible. Parts can split off an atom or it can |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1239 fission into two parts of roughly equal size. Physical atoms were named |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1240 prematurely, before their truer nature was found. In Lisp, certain |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1241 kinds of atom, such as an array, can be separated into parts; but the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1242 mechanism for doing this is different from the mechanism for splitting a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1243 list. As far as list operations are concerned, the atoms of a list are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1244 unsplittable. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1245 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1246 As in English, the meanings of the component letters of a Lisp atom |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1247 are different from the meaning the letters make as a word. For |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1248 example, the word for the South American sloth, the @samp{ai}, is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1249 completely different from the two words, @samp{a}, and @samp{i}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1251 There are many kinds of atom in nature but only a few in Lisp: for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1252 example, @dfn{numbers}, such as 37, 511, or 1729, and @dfn{symbols}, such |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1253 as @samp{+}, @samp{foo}, or @samp{forward-line}. The words we have |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1254 listed in the examples above are all symbols. In everyday Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1255 conversation, the word ``atom'' is not often used, because programmers |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1256 usually try to be more specific about what kind of atom they are dealing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1257 with. Lisp programming is mostly about symbols (and sometimes numbers) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1258 within lists. (Incidentally, the preceding three word parenthetical |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1259 remark is a proper list in Lisp, since it consists of atoms, which in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1260 this case are symbols, separated by whitespace and enclosed by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1261 parentheses, without any non-Lisp punctuation.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1262 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1263 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1264 In addition, text between double quotation marks---even sentences or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1265 paragraphs---is an atom. Here is an example: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1266 @cindex Text between double quotation marks |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1267 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1268 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1269 '(this list includes "text between quotation marks.") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1270 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1271 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1272 @cindex @samp{string} defined |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1273 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1274 In Lisp, all of the quoted text including the punctuation mark and the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1275 blank spaces is a single atom. This kind of atom is called a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1276 @dfn{string} (for `string of characters') and is the sort of thing that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1277 is used for messages that a computer can print for a human to read. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1278 Strings are a different kind of atom than numbers or symbols and are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1279 used differently. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1280 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1281 @node Whitespace in Lists, Typing Lists, Lisp Atoms, Lisp Lists |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1282 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1283 @subsection Whitespace in Lists |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1284 @cindex Whitespace in lists |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1285 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1286 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1287 The amount of whitespace in a list does not matter. From the point of view |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1288 of the Lisp language, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1289 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1290 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1291 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1292 '(this list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1293 looks like this) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1294 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1295 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1296 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1297 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1298 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1299 is exactly the same as this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1300 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1301 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1302 '(this list looks like this) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1303 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1304 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1305 Both examples show what to Lisp is the same list, the list made up of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1306 the symbols @samp{this}, @samp{list}, @samp{looks}, @samp{like}, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1307 @samp{this} in that order. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1308 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1309 Extra whitespace and newlines are designed to make a list more readable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1310 by humans. When Lisp reads the expression, it gets rid of all the extra |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1311 whitespace (but it needs to have at least one space between atoms in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1312 order to tell them apart.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1313 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1314 Odd as it seems, the examples we have seen cover almost all of what Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1315 lists look like! Every other list in Lisp looks more or less like one |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1316 of these examples, except that the list may be longer and more complex. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1317 In brief, a list is between parentheses, a string is between quotation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1318 marks, a symbol looks like a word, and a number looks like a number. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1319 (For certain situations, square brackets, dots and a few other special |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1320 characters may be used; however, we will go quite far without them.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1321 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1322 @node Typing Lists, , Whitespace in Lists, Lisp Lists |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1323 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1324 @subsection GNU Emacs Helps You Type Lists |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1325 @cindex Help typing lists |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1326 @cindex Formatting help |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1327 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1328 When you type a Lisp expression in GNU Emacs using either Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1329 Interaction mode or Emacs Lisp mode, you have available to you several |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1330 commands to format the Lisp expression so it is easy to read. For |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1331 example, pressing the @key{TAB} key automatically indents the line the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1332 cursor is on by the right amount. A command to properly indent the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1333 code in a region is customarily bound to @kbd{M-C-\}. Indentation is |
44899
ebddb2618c17
Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents:
43431
diff
changeset
|
1334 designed so that you can see which elements of a list belong to which |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1335 list---elements of a sub-list are indented more than the elements of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1336 the enclosing list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1337 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1338 In addition, when you type a closing parenthesis, Emacs momentarily |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1339 jumps the cursor back to the matching opening parenthesis, so you can |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1340 see which one it is. This is very useful, since every list you type |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1341 in Lisp must have its closing parenthesis match its opening |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1342 parenthesis. (@xref{Major Modes, , Major Modes, emacs, The GNU Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1343 Manual}, for more information about Emacs' modes.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1344 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1345 @node Run a Program, Making Errors, Lisp Lists, List Processing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1346 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1347 @section Run a Program |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1348 @cindex Run a program |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1349 @cindex Program, running one |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1350 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1351 @cindex @samp{evaluate} defined |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1352 A list in Lisp---any list---is a program ready to run. If you run it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1353 (for which the Lisp jargon is @dfn{evaluate}), the computer will do one |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1354 of three things: do nothing except return to you the list itself; send |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1355 you an error message; or, treat the first symbol in the list as a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1356 command to do something. (Usually, of course, it is the last of these |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1357 three things that you really want!) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1358 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1359 @c use code for the single apostrophe, not samp. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1360 The single apostrophe, @code{'}, that I put in front of some of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1361 example lists in preceding sections is called a @dfn{quote}; when it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1362 precedes a list, it tells Lisp to do nothing with the list, other than |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1363 take it as it is written. But if there is no quote preceding a list, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1364 the first item of the list is special: it is a command for the computer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1365 to obey. (In Lisp, these commands are called @emph{functions}.) The list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1366 @code{(+ 2 2)} shown above did not have a quote in front of it, so Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1367 understands that the @code{+} is an instruction to do something with the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1368 rest of the list: add the numbers that follow. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1369 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1370 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1371 If you are reading this inside of GNU Emacs in Info, here is how you can |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1372 evaluate such a list: place your cursor immediately after the right |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1373 hand parenthesis of the following list and then type @kbd{C-x C-e}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1374 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1375 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1376 (+ 2 2) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1377 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1378 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1379 @c use code for the number four, not samp. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1380 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1381 You will see the number @code{4} appear in the echo area. (In the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1382 jargon, what you have just done is ``evaluate the list.'' The echo area |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1383 is the line at the bottom of the screen that displays or ``echoes'' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1384 text.) Now try the same thing with a quoted list: place the cursor |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1385 right after the following list and type @kbd{C-x C-e}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1386 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1387 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1388 '(this is a quoted list) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1389 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1390 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1391 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1392 You will see @code{(this is a quoted list)} appear in the echo area. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1393 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1394 @cindex Lisp interpreter, explained |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1395 @cindex Interpreter, Lisp, explained |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1396 In both cases, what you are doing is giving a command to the program |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1397 inside of GNU Emacs called the @dfn{Lisp interpreter}---giving the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1398 interpreter a command to evaluate the expression. The name of the Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1399 interpreter comes from the word for the task done by a human who comes |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1400 up with the meaning of an expression---who ``interprets'' it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1401 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1402 You can also evaluate an atom that is not part of a list---one that is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1403 not surrounded by parentheses; again, the Lisp interpreter translates |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1404 from the humanly readable expression to the language of the computer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1405 But before discussing this (@pxref{Variables}), we will discuss what the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1406 Lisp interpreter does when you make an error. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1407 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1408 @node Making Errors, Names & Definitions, Run a Program, List Processing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1409 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1410 @section Generate an Error Message |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1411 @cindex Generate an error message |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1412 @cindex Error message generation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1413 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1414 Partly so you won't worry if you do it accidentally, we will now give |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1415 a command to the Lisp interpreter that generates an error message. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1416 This is a harmless activity; and indeed, we will often try to generate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1417 error messages intentionally. Once you understand the jargon, error |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1418 messages can be informative. Instead of being called ``error'' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1419 messages, they should be called ``help'' messages. They are like |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1420 signposts to a traveller in a strange country; deciphering them can be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1421 hard, but once understood, they can point the way. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1422 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1423 The error message is generated by a built-in GNU Emacs debugger. We |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1424 will `enter the debugger'. You get out of the debugger by typing @code{q}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1425 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1426 What we will do is evaluate a list that is not quoted and does not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1427 have a meaningful command as its first element. Here is a list almost |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1428 exactly the same as the one we just used, but without the single-quote |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1429 in front of it. Position the cursor right after it and type @kbd{C-x |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1430 C-e}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1431 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1432 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1433 (this is an unquoted list) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1434 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1435 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1436 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1437 What you see depends on which version of Emacs you are running. GNU |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1438 Emacs version 21 provides more information than version 20 and before. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1439 First, the more recent result of generating an error; then the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1440 earlier, version 20 result. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1441 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1442 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1443 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1444 In GNU Emacs version 21, a @file{*Backtrace*} window will open up and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1445 you will see the following in it: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1446 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1447 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1448 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1449 ---------- Buffer: *Backtrace* ---------- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1450 Debugger entered--Lisp error: (void-function this) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1451 (this is an unquoted list) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1452 eval((this is an unquoted list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1453 eval-last-sexp-1(nil) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1454 eval-last-sexp(nil) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1455 call-interactively(eval-last-sexp) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1456 ---------- Buffer: *Backtrace* ---------- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1457 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1458 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1459 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1460 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1461 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1462 Your cursor will be in this window (you may have to wait a few seconds |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1463 before it becomes visible). To quit the debugger and make the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1464 debugger window go away, type: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1465 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1466 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1467 q |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1468 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1469 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1470 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1471 Please type @kbd{q} right now, so you become confident that you can |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1472 get out of the debugger. Then, type @kbd{C-x C-e} again to re-enter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1473 it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1474 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1475 @cindex @samp{function} defined |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1476 Based on what we already know, we can almost read this error message. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1477 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1478 You read the @file{*Backtrace*} buffer from the bottom up; it tells |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1479 you what Emacs did. When you typed @kbd{C-x C-e}, you made an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1480 interactive call to the command @code{eval-last-sexp}. @code{eval} is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1481 an abbreviation for `evaluate' and @code{sexp} is an abbreviation for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1482 `symbolic expression'. The command means `evaluate last symbolic |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1483 expression', which is the expression just before your cursor. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1484 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1485 Each line above tells you what the Lisp interpreter evaluated next. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1486 The most recent action is at the top. The buffer is called the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1487 @file{*Backtrace*} buffer because it enables you to track Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1488 backwards. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1489 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1490 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1491 At the top of the @file{*Backtrace*} buffer, you see the line: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1492 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1493 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1494 Debugger entered--Lisp error: (void-function this) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1495 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1496 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1497 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1498 The Lisp interpreter tried to evaluate the first atom of the list, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1499 word @samp{this}. It is this action that generated the error message |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1500 @samp{void-function this}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1501 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1502 The message contains the words @samp{void-function} and @samp{this}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1503 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1504 @cindex @samp{function} defined |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1505 The word @samp{function} was mentioned once before. It is a very |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1506 important word. For our purposes, we can define it by saying that a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1507 @dfn{function} is a set of instructions to the computer that tell the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1508 computer to do something. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1509 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1510 Now we can begin to understand the error message: @samp{void-function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1511 this}. The function (that is, the word @samp{this}) does not have a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1512 definition of any set of instructions for the computer to carry out. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1513 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1514 The slightly odd word, @samp{void-function}, is designed to cover the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1515 way Emacs Lisp is implemented, which is that when a symbol does not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1516 have a function definition attached to it, the place that should |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1517 contain the instructions is `void'. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1518 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1519 On the other hand, since we were able to add 2 plus 2 successfully, by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1520 evaluating @code{(+ 2 2)}, we can infer that the symbol @code{+} must |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1521 have a set of instructions for the computer to obey and those |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1522 instructions must be to add the numbers that follow the @code{+}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1523 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1524 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1525 In GNU Emacs version 20, and in earlier versions, you will see only |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1526 one line of error message; it will appear in the echo area and look |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1527 like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1528 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1529 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1530 Symbol's function definition is void:@: this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1531 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1532 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1533 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1534 (Also, your terminal may beep at you---some do, some don't; and others |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1535 blink. This is just a device to get your attention.) The message goes |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1536 away as soon as you type another key, even just to move the cursor. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1537 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1538 We know the meaning of the word @samp{Symbol}. It refers to the first |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1539 atom of the list, the word @samp{this}. The word @samp{function} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1540 refers to the instructions that tell the computer what to do. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1541 (Technically, the symbol tells the computer where to find the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1542 instructions, but this is a complication we can ignore for the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1543 moment.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1544 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1545 The error message can be understood: @samp{Symbol's function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1546 definition is void:@: this}. The symbol (that is, the word |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1547 @samp{this}) lacks instructions for the computer to carry out. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1548 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1549 @node Names & Definitions, Lisp Interpreter, Making Errors, List Processing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1550 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1551 @section Symbol Names and Function Definitions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1552 @cindex Symbol names |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1553 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1554 We can articulate another characteristic of Lisp based on what we have |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1555 discussed so far---an important characteristic: a symbol, like |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1556 @code{+}, is not itself the set of instructions for the computer to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1557 carry out. Instead, the symbol is used, perhaps temporarily, as a way |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1558 of locating the definition or set of instructions. What we see is the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1559 name through which the instructions can be found. Names of people |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1560 work the same way. I can be referred to as @samp{Bob}; however, I am |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1561 not the letters @samp{B}, @samp{o}, @samp{b} but am the consciousness |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1562 consistently associated with a particular life-form. The name is not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1563 me, but it can be used to refer to me. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1564 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1565 In Lisp, one set of instructions can be attached to several names. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1566 For example, the computer instructions for adding numbers can be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1567 linked to the symbol @code{plus} as well as to the symbol @code{+} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1568 (and are in some dialects of Lisp). Among humans, I can be referred |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1569 to as @samp{Robert} as well as @samp{Bob} and by other words as well. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1570 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1571 On the other hand, a symbol can have only one function definition |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1572 attached to it at a time. Otherwise, the computer would be confused as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1573 to which definition to use. If this were the case among people, only |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1574 one person in the world could be named @samp{Bob}. However, the function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1575 definition to which the name refers can be changed readily. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1576 (@xref{Install, , Install a Function Definition}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1577 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1578 Since Emacs Lisp is large, it is customary to name symbols in a way |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1579 that identifies the part of Emacs to which the function belongs. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1580 Thus, all the names for functions that deal with Texinfo start with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1581 @samp{texinfo-} and those for functions that deal with reading mail |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1582 start with @samp{rmail-}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1583 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1584 @node Lisp Interpreter, Evaluation, Names & Definitions, List Processing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1585 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1586 @section The Lisp Interpreter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1587 @cindex Lisp interpreter, what it does |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1588 @cindex Interpreter, what it does |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1589 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1590 Based on what we have seen, we can now start to figure out what the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1591 Lisp interpreter does when we command it to evaluate a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1592 First, it looks to see whether there is a quote before the list; if |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1593 there is, the interpreter just gives us the list. On the other |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1594 hand, if there is no quote, the interpreter looks at the first element |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1595 in the list and sees whether it has a function definition. If it does, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1596 the interpreter carries out the instructions in the function definition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1597 Otherwise, the interpreter prints an error message. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1598 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1599 This is how Lisp works. Simple. There are added complications which we |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1600 will get to in a minute, but these are the fundamentals. Of course, to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1601 write Lisp programs, you need to know how to write function definitions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1602 and attach them to names, and how to do this without confusing either |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1603 yourself or the computer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1604 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1605 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1606 * Complications:: Variables, Special forms, Lists within. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1607 * Byte Compiling:: Specially processing code for speed. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1608 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1609 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1610 @node Complications, Byte Compiling, Lisp Interpreter, Lisp Interpreter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1611 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1612 @unnumberedsubsec Complications |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1613 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1614 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1615 Now, for the first complication. In addition to lists, the Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1616 interpreter can evaluate a symbol that is not quoted and does not have |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1617 parentheses around it. The Lisp interpreter will attempt to determine |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1618 the symbol's value as a @dfn{variable}. This situation is described |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1619 in the section on variables. (@xref{Variables}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1620 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1621 @cindex Special form |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1622 The second complication occurs because some functions are unusual and do |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1623 not work in the usual manner. Those that don't are called @dfn{special |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1624 forms}. They are used for special jobs, like defining a function, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1625 there are not many of them. In the next few chapters, you will be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1626 introduced to several of the more important special forms. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1627 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1628 The third and final complication is this: if the function that the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1629 Lisp interpreter is looking at is not a special form, and if it is part |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1630 of a list, the Lisp interpreter looks to see whether the list has a list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1631 inside of it. If there is an inner list, the Lisp interpreter first |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1632 figures out what it should do with the inside list, and then it works on |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1633 the outside list. If there is yet another list embedded inside the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1634 inner list, it works on that one first, and so on. It always works on |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1635 the innermost list first. The interpreter works on the innermost list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1636 first, to evaluate the result of that list. The result may be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1637 used by the enclosing expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1638 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1639 Otherwise, the interpreter works left to right, from one expression to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1640 the next. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1641 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1642 @node Byte Compiling, , Complications, Lisp Interpreter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1643 @subsection Byte Compiling |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1644 @cindex Byte compiling |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1645 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1646 One other aspect of interpreting: the Lisp interpreter is able to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1647 interpret two kinds of entity: humanly readable code, on which we will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1648 focus exclusively, and specially processed code, called @dfn{byte |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1649 compiled} code, which is not humanly readable. Byte compiled code |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1650 runs faster than humanly readable code. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1651 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1652 You can transform humanly readable code into byte compiled code by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1653 running one of the compile commands such as @code{byte-compile-file}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1654 Byte compiled code is usually stored in a file that ends with a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1655 @file{.elc} extension rather than a @file{.el} extension. You will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1656 see both kinds of file in the @file{emacs/lisp} directory; the files |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1657 to read are those with @file{.el} extensions. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1658 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1659 As a practical matter, for most things you might do to customize or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1660 extend Emacs, you do not need to byte compile; and I will not discuss |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1661 the topic here. @xref{Byte Compilation, , Byte Compilation, elisp, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1662 The GNU Emacs Lisp Reference Manual}, for a full description of byte |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1663 compilation. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1664 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1665 @node Evaluation, Variables, Lisp Interpreter, List Processing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1666 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1667 @section Evaluation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1668 @cindex Evaluation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1669 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1670 When the Lisp interpreter works on an expression, the term for the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1671 activity is called @dfn{evaluation}. We say that the interpreter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1672 `evaluates the expression'. I've used this term several times before. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1673 The word comes from its use in everyday language, `to ascertain the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1674 value or amount of; to appraise', according to @cite{Webster's New |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1675 Collegiate Dictionary}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1676 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1677 After evaluating an expression, the Lisp interpreter will most likely |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1678 @dfn{return} the value that the computer produces by carrying out the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1679 instructions it found in the function definition, or perhaps it will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1680 give up on that function and produce an error message. (The interpreter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1681 may also find itself tossed, so to speak, to a different function or it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1682 may attempt to repeat continually what it is doing for ever and ever in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1683 what is called an `infinite loop'. These actions are less common; and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1684 we can ignore them.) Most frequently, the interpreter returns a value. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1685 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1686 @cindex @samp{side effect} defined |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1687 At the same time the interpreter returns a value, it may do something |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1688 else as well, such as move a cursor or copy a file; this other kind of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1689 action is called a @dfn{side effect}. Actions that we humans think are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1690 important, such as printing results, are often ``side effects'' to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1691 Lisp interpreter. The jargon can sound peculiar, but it turns out that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1692 it is fairly easy to learn to use side effects. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1693 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1694 In summary, evaluating a symbolic expression most commonly causes the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1695 Lisp interpreter to return a value and perhaps carry out a side effect; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1696 or else produce an error. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1697 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1698 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1699 * Evaluating Inner Lists:: Lists within lists... |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1700 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1701 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1702 @node Evaluating Inner Lists, , Evaluation, Evaluation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1703 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1704 @subsection Evaluating Inner Lists |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1705 @cindex Inner list evaluation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1706 @cindex Evaluating inner lists |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1707 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1708 If evaluation applies to a list that is inside another list, the outer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1709 list may use the value returned by the first evaluation as information |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1710 when the outer list is evaluated. This explains why inner expressions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1711 are evaluated first: the values they return are used by the outer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1712 expressions. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1713 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1714 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1715 We can investigate this process by evaluating another addition example. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1716 Place your cursor after the following expression and type @kbd{C-x C-e}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1717 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1718 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1719 (+ 2 (+ 3 3)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1720 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1721 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1722 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1723 The number 8 will appear in the echo area. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1724 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1725 What happens is that the Lisp interpreter first evaluates the inner |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1726 expression, @code{(+ 3 3)}, for which the value 6 is returned; then it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1727 evaluates the outer expression as if it were written @code{(+ 2 6)}, which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1728 returns the value 8. Since there are no more enclosing expressions to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1729 evaluate, the interpreter prints that value in the echo area. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1730 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1731 Now it is easy to understand the name of the command invoked by the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1732 keystrokes @kbd{C-x C-e}: the name is @code{eval-last-sexp}. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1733 letters @code{sexp} are an abbreviation for `symbolic expression', and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1734 @code{eval} is an abbreviation for `evaluate'. The command means |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1735 `evaluate last symbolic expression'. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1736 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1737 As an experiment, you can try evaluating the expression by putting the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1738 cursor at the beginning of the next line immediately following the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1739 expression, or inside the expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1740 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1741 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1742 Here is another copy of the expression: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1743 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1744 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1745 (+ 2 (+ 3 3)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1746 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1747 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1748 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1749 If you place the cursor at the beginning of the blank line that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1750 immediately follows the expression and type @kbd{C-x C-e}, you will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1751 still get the value 8 printed in the echo area. Now try putting the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1752 cursor inside the expression. If you put it right after the next to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1753 last parenthesis (so it appears to sit on top of the last parenthesis), |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1754 you will get a 6 printed in the echo area! This is because the command |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1755 evaluates the expression @code{(+ 3 3)}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1756 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1757 Now put the cursor immediately after a number. Type @kbd{C-x C-e} and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1758 you will get the number itself. In Lisp, if you evaluate a number, you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1759 get the number itself---this is how numbers differ from symbols. If you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1760 evaluate a list starting with a symbol like @code{+}, you will get a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1761 value returned that is the result of the computer carrying out the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1762 instructions in the function definition attached to that name. If a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1763 symbol by itself is evaluated, something different happens, as we will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1764 see in the next section. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1765 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1766 @node Variables, Arguments, Evaluation, List Processing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1767 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1768 @section Variables |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1769 @cindex Variables |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1770 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1771 In Emacs Lisp, a symbol can have a value attached to it just as it can |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1772 have a function definition attached to it. The two are different. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1773 The function definition is a set of instructions that a computer will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1774 obey. A value, on the other hand, is something, such as number or a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1775 name, that can vary (which is why such a symbol is called a variable). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1776 The value of a symbol can be any expression in Lisp, such as a symbol, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1777 number, list, or string. A symbol that has a value is often called a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1778 @dfn{variable}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1779 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1780 A symbol can have both a function definition and a value attached to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1781 it at the same time. Or it can have just one or the other. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1782 The two are separate. This is somewhat similar |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1783 to the way the name Cambridge can refer to the city in Massachusetts |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1784 and have some information attached to the name as well, such as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1785 ``great programming center''. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1786 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1787 @ignore |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1788 (Incidentally, in Emacs Lisp, a symbol can have two |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1789 other things attached to it, too: a property list and a documentation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1790 string; these are discussed later.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1791 @end ignore |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1792 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1793 Another way to think about this is to imagine a symbol as being a chest |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1794 of drawers. The function definition is put in one drawer, the value in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1795 another, and so on. What is put in the drawer holding the value can be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1796 changed without affecting the contents of the drawer holding the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1797 function definition, and vice-versa. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1798 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1799 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1800 * fill-column Example:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1801 * Void Function:: The error message for a symbol |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1802 without a function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1803 * Void Variable:: The error message for a symbol without a value. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1804 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1805 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1806 @node fill-column Example, Void Function, Variables, Variables |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1807 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1808 @unnumberedsubsec @code{fill-column}, an Example Variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1809 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1810 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1811 @findex fill-column, @r{an example variable} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1812 @cindex Example variable, @code{fill-column} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1813 @cindex Variable, example of, @code{fill-column} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1814 The variable @code{fill-column} illustrates a symbol with a value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1815 attached to it: in every GNU Emacs buffer, this symbol is set to some |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1816 value, usually 72 or 70, but sometimes to some other value. To find the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1817 value of this symbol, evaluate it by itself. If you are reading this in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1818 Info inside of GNU Emacs, you can do this by putting the cursor after |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1819 the symbol and typing @kbd{C-x C-e}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1820 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1821 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1822 fill-column |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1823 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1824 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1825 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1826 After I typed @kbd{C-x C-e}, Emacs printed the number 72 in my echo |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1827 area. This is the value for which @code{fill-column} is set for me as I |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1828 write this. It may be different for you in your Info buffer. Notice |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1829 that the value returned as a variable is printed in exactly the same way |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1830 as the value returned by a function carrying out its instructions. From |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1831 the point of view of the Lisp interpreter, a value returned is a value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1832 returned. What kind of expression it came from ceases to matter once |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1833 the value is known. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1834 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1835 A symbol can have any value attached to it or, to use the jargon, we can |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1836 @dfn{bind} the variable to a value: to a number, such as 72; to a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1837 string, @code{"such as this"}; to a list, such as @code{(spruce pine |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1838 oak)}; we can even bind a variable to a function definition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1839 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1840 A symbol can be bound to a value in several ways. @xref{set & setq, , |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1841 Setting the Value of a Variable}, for information about one way to do |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1842 this. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1843 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1844 @node Void Function, Void Variable, fill-column Example, Variables |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1845 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1846 @subsection Error Message for a Symbol Without a Function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1847 @cindex Symbol without function error |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1848 @cindex Error for symbol without function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1849 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1850 When we evaluated @code{fill-column} to find its value as a variable, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1851 we did not place parentheses around the word. This is because we did |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1852 not intend to use it as a function name. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1853 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1854 If @code{fill-column} were the first or only element of a list, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1855 Lisp interpreter would attempt to find the function definition |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1856 attached to it. But @code{fill-column} has no function definition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1857 Try evaluating this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1858 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1859 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1860 (fill-column) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1861 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1862 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1863 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1864 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1865 In GNU Emacs version 21, you will create a @file{*Backtrace*} buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1866 that says: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1867 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1868 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1869 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1870 ---------- Buffer: *Backtrace* ---------- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1871 Debugger entered--Lisp error: (void-function fill-column) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1872 (fill-column) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1873 eval((fill-column)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1874 eval-last-sexp-1(nil) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1875 eval-last-sexp(nil) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1876 call-interactively(eval-last-sexp) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1877 ---------- Buffer: *Backtrace* ---------- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1878 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1879 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1880 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1881 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1882 (Remember, to quit the debugger and make the debugger window go away, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1883 type @kbd{q} in the @file{*Backtrace*} buffer.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1884 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1885 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1886 In GNU Emacs 20 and before, you will produce an error message that says: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1887 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1888 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1889 Symbol's function definition is void:@: fill-column |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1890 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1891 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1892 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1893 (The message will go away away as soon as you move the cursor or type |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1894 another key.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1895 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1896 @node Void Variable, , Void Function, Variables |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1897 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1898 @subsection Error Message for a Symbol Without a Value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1899 @cindex Symbol without value error |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1900 @cindex Error for symbol without value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1901 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1902 If you attempt to evaluate a symbol that does not have a value bound to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1903 it, you will receive an error message. You can see this by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1904 experimenting with our 2 plus 2 addition. In the following expression, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1905 put your cursor right after the @code{+}, before the first number 2, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1906 type @kbd{C-x C-e}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1907 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1908 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1909 (+ 2 2) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1910 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1911 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1912 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1913 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1914 In GNU Emacs 21, you will create a @file{*Backtrace*} buffer that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1915 says: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1916 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1917 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1918 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1919 ---------- Buffer: *Backtrace* ---------- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1920 Debugger entered--Lisp error: (void-variable +) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1921 eval(+) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1922 eval-last-sexp-1(nil) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1923 eval-last-sexp(nil) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1924 call-interactively(eval-last-sexp) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1925 ---------- Buffer: *Backtrace* ---------- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1926 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1927 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1928 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1929 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1930 (As with the other times we entered the debugger, you can quit by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1931 typing @kbd{q} in the @file{*Backtrace*} buffer.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1932 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1933 This backtrace is different from the very first error message we saw, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1934 which said, @samp{Debugger entered--Lisp error: (void-function this)}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1935 In this case, the function does not have a value as a variable; while |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1936 in the other error message, the function (the word `this') did not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1937 have a definition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1938 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1939 In this experiment with the @code{+}, what we did was cause the Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1940 interpreter to evaluate the @code{+} and look for the value of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1941 variable instead of the function definition. We did this by placing the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1942 cursor right after the symbol rather than after the parenthesis of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1943 enclosing list as we did before. As a consequence, the Lisp interpreter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1944 evaluated the preceding s-expression, which in this case was the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1945 @code{+} by itself. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1946 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1947 Since @code{+} does not have a value bound to it, just the function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1948 definition, the error message reported that the symbol's value as a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1949 variable was void. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1950 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1951 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1952 In GNU Emacs version 20 and before, your error message will say: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1953 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1954 @example |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1955 Symbol's value as variable is void:@: + |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1956 @end example |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1957 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1958 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1959 The meaning is the same as in GNU Emacs 21. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1960 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1961 @node Arguments, set & setq, Variables, List Processing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1962 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1963 @section Arguments |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1964 @cindex Arguments |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1965 @cindex Passing information to functions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1966 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1967 To see how information is passed to functions, let's look again at |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1968 our old standby, the addition of two plus two. In Lisp, this is written |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1969 as follows: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1970 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1971 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1972 (+ 2 2) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1973 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1974 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1975 If you evaluate this expression, the number 4 will appear in your echo |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1976 area. What the Lisp interpreter does is add the numbers that follow |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1977 the @code{+}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1978 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1979 @cindex @samp{argument} defined |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1980 The numbers added by @code{+} are called the @dfn{arguments} of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1981 function @code{+}. These numbers are the information that is given to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1982 or @dfn{passed} to the function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1983 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1984 The word `argument' comes from the way it is used in mathematics and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1985 does not refer to a disputation between two people; instead it refers to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1986 the information presented to the function, in this case, to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1987 @code{+}. In Lisp, the arguments to a function are the atoms or lists |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1988 that follow the function. The values returned by the evaluation of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1989 these atoms or lists are passed to the function. Different functions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1990 require different numbers of arguments; some functions require none at |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1991 all.@footnote{It is curious to track the path by which the word `argument' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1992 came to have two different meanings, one in mathematics and the other in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1993 everyday English. According to the @cite{Oxford English Dictionary}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1994 the word derives from the Latin for @samp{to make clear, prove}; thus it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1995 came to mean, by one thread of derivation, `the evidence offered as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1996 proof', which is to say, `the information offered', which led to its |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1997 meaning in Lisp. But in the other thread of derivation, it came to mean |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1998 `to assert in a manner against which others may make counter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
1999 assertions', which led to the meaning of the word as a disputation. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2000 (Note here that the English word has two different definitions attached |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2001 to it at the same time. By contrast, in Emacs Lisp, a symbol cannot |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2002 have two different function definitions at the same time.)} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2003 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2004 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2005 * Data types:: Types of data passed to a function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2006 * Args as Variable or List:: An argument can be the value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2007 of a variable or list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2008 * Variable Number of Arguments:: Some functions may take a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2009 variable number of arguments. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2010 * Wrong Type of Argument:: Passing an argument of the wrong type |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2011 to a function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2012 * message:: A useful function for sending messages. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2013 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2014 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2015 @node Data types, Args as Variable or List, Arguments, Arguments |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2016 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2017 @subsection Arguments' Data Types |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2018 @cindex Data types |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2019 @cindex Types of data |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2020 @cindex Arguments' data types |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2021 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2022 The type of data that should be passed to a function depends on what |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2023 kind of information it uses. The arguments to a function such as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2024 @code{+} must have values that are numbers, since @code{+} adds numbers. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2025 Other functions use different kinds of data for their arguments. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2026 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2027 @findex concat |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2028 For example, the @code{concat} function links together or unites two or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2029 more strings of text to produce a string. The arguments are strings. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2030 Concatenating the two character strings @code{abc}, @code{def} produces |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2031 the single string @code{abcdef}. This can be seen by evaluating the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2032 following: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2033 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2034 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2035 (concat "abc" "def") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2036 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2037 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2038 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2039 The value produced by evaluating this expression is @code{"abcdef"}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2040 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2041 A function such as @code{substring} uses both a string and numbers as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2042 arguments. The function returns a part of the string, a substring of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2043 the first argument. This function takes three arguments. Its first |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2044 argument is the string of characters, the second and third arguments are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2045 numbers that indicate the beginning and end of the substring. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2046 numbers are a count of the number of characters (including spaces and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2047 punctuations) from the beginning of the string. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2048 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2049 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2050 For example, if you evaluate the following: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2051 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2052 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2053 (substring "The quick brown fox jumped." 16 19) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2054 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2055 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2056 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2057 you will see @code{"fox"} appear in the echo area. The arguments are the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2058 string and the two numbers. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2059 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2060 Note that the string passed to @code{substring} is a single atom even |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2061 though it is made up of several words separated by spaces. Lisp counts |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2062 everything between the two quotation marks as part of the string, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2063 including the spaces. You can think of the @code{substring} function as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2064 a kind of `atom smasher' since it takes an otherwise indivisible atom |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2065 and extracts a part. However, @code{substring} is only able to extract |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2066 a substring from an argument that is a string, not from another type of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2067 atom such as a number or symbol. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2068 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2069 @node Args as Variable or List, Variable Number of Arguments, Data types, Arguments |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2070 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2071 @subsection An Argument as the Value of a Variable or List |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2072 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2073 An argument can be a symbol that returns a value when it is evaluated. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2074 For example, when the symbol @code{fill-column} by itself is evaluated, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2075 it returns a number. This number can be used in an addition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2076 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2077 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2078 Position the cursor after the following expression and type @kbd{C-x |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2079 C-e}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2080 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2081 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2082 (+ 2 fill-column) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2083 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2084 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2085 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2086 The value will be a number two more than what you get by evaluating |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2087 @code{fill-column} alone. For me, this is 74, because the value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2088 @code{fill-column} is 72. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2089 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2090 As we have just seen, an argument can be a symbol that returns a value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2091 when evaluated. In addition, an argument can be a list that returns a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2092 value when it is evaluated. For example, in the following expression, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2093 the arguments to the function @code{concat} are the strings |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2094 @w{@code{"The "}} and @w{@code{" red foxes."}} and the list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2095 @code{(number-to-string (+ 2 fill-column))}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2096 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2097 @c For Emacs 21, need number-to-string |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2098 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2099 (concat "The " (number-to-string (+ 2 fill-column)) " red foxes.") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2100 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2101 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2102 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2103 If you evaluate this expression---and if, as with my Emacs, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2104 @code{fill-column} evaluates to 72---@code{"The 74 red foxes."} will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2105 appear in the echo area. (Note that you must put spaces after the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2106 word @samp{The} and before the word @samp{red} so they will appear in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2107 the final string. The function @code{number-to-string} converts the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2108 integer that the addition function returns to a string. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2109 @code{number-to-string} is also known as @code{int-to-string}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2110 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2111 @node Variable Number of Arguments, Wrong Type of Argument, Args as Variable or List, Arguments |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2112 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2113 @subsection Variable Number of Arguments |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2114 @cindex Variable number of arguments |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2115 @cindex Arguments, variable number of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2116 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2117 Some functions, such as @code{concat}, @code{+} or @code{*}, take any |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2118 number of arguments. (The @code{*} is the symbol for multiplication.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2119 This can be seen by evaluating each of the following expressions in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2120 the usual way. What you will see in the echo area is printed in this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2121 text after @samp{@result{}}, which you may read as `evaluates to'. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2122 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2123 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2124 In the first set, the functions have no arguments: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2125 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2126 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2127 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2128 (+) @result{} 0 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2129 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2130 (*) @result{} 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2131 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2132 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2133 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2134 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2135 In this set, the functions have one argument each: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2136 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2137 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2138 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2139 (+ 3) @result{} 3 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2140 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2141 (* 3) @result{} 3 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2142 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2143 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2144 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2145 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2146 In this set, the functions have three arguments each: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2147 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2148 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2149 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2150 (+ 3 4 5) @result{} 12 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2151 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2152 (* 3 4 5) @result{} 60 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2153 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2154 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2155 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2156 @node Wrong Type of Argument, message, Variable Number of Arguments, Arguments |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2157 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2158 @subsection Using the Wrong Type Object as an Argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2159 @cindex Wrong type of argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2160 @cindex Argument, wrong type of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2161 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2162 When a function is passed an argument of the wrong type, the Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2163 interpreter produces an error message. For example, the @code{+} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2164 function expects the values of its arguments to be numbers. As an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2165 experiment we can pass it the quoted symbol @code{hello} instead of a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2166 number. Position the cursor after the following expression and type |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2167 @kbd{C-x C-e}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2168 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2169 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2170 (+ 2 'hello) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2171 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2172 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2173 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2174 When you do this you will generate an error message. What has happened |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2175 is that @code{+} has tried to add the 2 to the value returned by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2176 @code{'hello}, but the value returned by @code{'hello} is the symbol |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2177 @code{hello}, not a number. Only numbers can be added. So @code{+} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2178 could not carry out its addition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2179 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2180 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2181 In GNU Emacs version 21, you will create and enter a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2182 @file{*Backtrace*} buffer that says: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2183 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2184 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2185 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2186 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2187 ---------- Buffer: *Backtrace* ---------- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2188 Debugger entered--Lisp error: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2189 (wrong-type-argument number-or-marker-p hello) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2190 +(2 hello) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2191 eval((+ 2 (quote hello))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2192 eval-last-sexp-1(nil) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2193 eval-last-sexp(nil) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2194 call-interactively(eval-last-sexp) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2195 ---------- Buffer: *Backtrace* ---------- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2196 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2197 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2198 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2199 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2200 As usual, the error message tries to be helpful and makes sense after you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2201 learn how to read it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2202 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2203 The first part of the error message is straightforward; it says |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2204 @samp{wrong type argument}. Next comes the mysterious jargon word |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2205 @w{@samp{number-or-marker-p}}. This word is trying to tell you what |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2206 kind of argument the @code{+} expected. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2207 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2208 The symbol @code{number-or-marker-p} says that the Lisp interpreter is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2209 trying to determine whether the information presented it (the value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2210 the argument) is a number or a marker (a special object representing a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2211 buffer position). What it does is test to see whether the @code{+} is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2212 being given numbers to add. It also tests to see whether the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2213 argument is something called a marker, which is a specific feature of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2214 Emacs Lisp. (In Emacs, locations in a buffer are recorded as markers. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2215 When the mark is set with the @kbd{C-@@} or @kbd{C-@key{SPC}} command, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2216 its position is kept as a marker. The mark can be considered a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2217 number---the number of characters the location is from the beginning |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2218 of the buffer.) In Emacs Lisp, @code{+} can be used to add the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2219 numeric value of marker positions as numbers. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2220 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2221 The @samp{p} of @code{number-or-marker-p} is the embodiment of a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2222 practice started in the early days of Lisp programming. The @samp{p} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2223 stands for `predicate'. In the jargon used by the early Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2224 researchers, a predicate refers to a function to determine whether some |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2225 property is true or false. So the @samp{p} tells us that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2226 @code{number-or-marker-p} is the name of a function that determines |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2227 whether it is true or false that the argument supplied is a number or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2228 a marker. Other Lisp symbols that end in @samp{p} include @code{zerop}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2229 a function that tests whether its argument has the value of zero, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2230 @code{listp}, a function that tests whether its argument is a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2231 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2232 Finally, the last part of the error message is the symbol @code{hello}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2233 This is the value of the argument that was passed to @code{+}. If the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2234 addition had been passed the correct type of object, the value passed |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2235 would have been a number, such as 37, rather than a symbol like |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2236 @code{hello}. But then you would not have got the error message. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2237 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2238 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2239 In GNU Emacs version 20 and before, the echo area displays an error |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2240 message that says: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2241 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2242 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2243 Wrong type argument:@: number-or-marker-p, hello |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2244 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2245 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2246 This says, in different words, the same as the top line of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2247 @file{*Backtrace*} buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2248 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2249 @node message, , Wrong Type of Argument, Arguments |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2250 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2251 @subsection The @code{message} Function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2252 @findex message |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2253 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2254 Like @code{+}, the @code{message} function takes a variable number of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2255 arguments. It is used to send messages to the user and is so useful |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2256 that we will describe it here. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2257 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2258 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2259 A message is printed in the echo area. For example, you can print a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2260 message in your echo area by evaluating the following list: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2261 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2262 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2263 (message "This message appears in the echo area!") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2264 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2265 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2266 The whole string between double quotation marks is a single argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2267 and is printed @i{in toto}. (Note that in this example, the message |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2268 itself will appear in the echo area within double quotes; that is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2269 because you see the value returned by the @code{message} function. In |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2270 most uses of @code{message} in programs that you write, the text will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2271 be printed in the echo area as a side-effect, without the quotes. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2272 @xref{multiply-by-seven in detail, , @code{multiply-by-seven} in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2273 detail}, for an example of this.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2274 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2275 However, if there is a @samp{%s} in the quoted string of characters, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2276 @code{message} function does not print the @samp{%s} as such, but looks |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2277 to the argument that follows the string. It evaluates the second |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2278 argument and prints the value at the location in the string where the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2279 @samp{%s} is. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2280 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2281 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2282 You can see this by positioning the cursor after the following |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2283 expression and typing @kbd{C-x C-e}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2284 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2285 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2286 (message "The name of this buffer is: %s." (buffer-name)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2287 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2288 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2289 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2290 In Info, @code{"The name of this buffer is: *info*."} will appear in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2291 echo area. The function @code{buffer-name} returns the name of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2292 buffer as a string, which the @code{message} function inserts in place |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2293 of @code{%s}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2294 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2295 To print a value as an integer, use @samp{%d} in the same way as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2296 @samp{%s}. For example, to print a message in the echo area that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2297 states the value of the @code{fill-column}, evaluate the following: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2298 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2299 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2300 (message "The value of fill-column is %d." fill-column) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2301 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2302 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2303 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2304 On my system, when I evaluate this list, @code{"The value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2305 fill-column is 72."} appears in my echo area@footnote{Actually, you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2306 can use @code{%s} to print a number. It is non-specific. @code{%d} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2307 prints only the part of a number left of a decimal point, and not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2308 anything that is not a number.}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2309 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2310 If there is more than one @samp{%s} in the quoted string, the value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2311 the first argument following the quoted string is printed at the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2312 location of the first @samp{%s} and the value of the second argument is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2313 printed at the location of the second @samp{%s}, and so on. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2314 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2315 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2316 For example, if you evaluate the following, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2317 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2318 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2319 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2320 (message "There are %d %s in the office!" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2321 (- fill-column 14) "pink elephants") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2322 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2323 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2324 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2325 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2326 a rather whimsical message will appear in your echo area. On my system |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2327 it says, @code{"There are 58 pink elephants in the office!"}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2328 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2329 The expression @code{(- fill-column 14)} is evaluated and the resulting |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2330 number is inserted in place of the @samp{%d}; and the string in double |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2331 quotes, @code{"pink elephants"}, is treated as a single argument and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2332 inserted in place of the @samp{%s}. (That is to say, a string between |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2333 double quotes evaluates to itself, like a number.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2334 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2335 Finally, here is a somewhat complex example that not only illustrates |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2336 the computation of a number, but also shows how you can use an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2337 expression within an expression to generate the text that is substituted |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2338 for @samp{%s}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2339 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2340 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2341 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2342 (message "He saw %d %s" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2343 (- fill-column 34) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2344 (concat "red " |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2345 (substring |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2346 "The quick brown foxes jumped." 16 21) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2347 " leaping.")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2348 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2349 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2350 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2351 In this example, @code{message} has three arguments: the string, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2352 @code{"He saw %d %s"}, the expression, @code{(- fill-column 32)}, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2353 the expression beginning with the function @code{concat}. The value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2354 resulting from the evaluation of @code{(- fill-column 32)} is inserted |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2355 in place of the @samp{%d}; and the value returned by the expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2356 beginning with @code{concat} is inserted in place of the @samp{%s}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2357 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2358 When I evaluate the expression, the message @code{"He saw 38 red |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2359 foxes leaping."} appears in my echo area. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2360 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2361 @node set & setq, Summary, Arguments, List Processing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2362 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2363 @section Setting the Value of a Variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2364 @cindex Variable, setting value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2365 @cindex Setting value of variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2366 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2367 @cindex @samp{bind} defined |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2368 There are several ways by which a variable can be given a value. One of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2369 the ways is to use either the function @code{set} or the function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2370 @code{setq}. Another way is to use @code{let} (@pxref{let}). (The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2371 jargon for this process is to @dfn{bind} a variable to a value.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2372 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2373 The following sections not only describe how @code{set} and @code{setq} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2374 work but also illustrate how arguments are passed. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2375 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2376 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2377 * Using set:: Setting values. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2378 * Using setq:: Setting a quoted value. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2379 * Counting:: Using @code{setq} to count. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2380 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2381 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2382 @node Using set, Using setq, set & setq, set & setq |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2383 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2384 @subsection Using @code{set} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2385 @findex set |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2386 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2387 To set the value of the symbol @code{flowers} to the list @code{'(rose |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2388 violet daisy buttercup)}, evaluate the following expression by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2389 positioning the cursor after the expression and typing @kbd{C-x C-e}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2390 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2391 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2392 (set 'flowers '(rose violet daisy buttercup)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2393 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2394 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2395 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2396 The list @code{(rose violet daisy buttercup)} will appear in the echo |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2397 area. This is what is @emph{returned} by the @code{set} function. As a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2398 side effect, the symbol @code{flowers} is bound to the list ; that is, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2399 the symbol @code{flowers}, which can be viewed as a variable, is given |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2400 the list as its value. (This process, by the way, illustrates how a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2401 side effect to the Lisp interpreter, setting the value, can be the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2402 primary effect that we humans are interested in. This is because every |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2403 Lisp function must return a value if it does not get an error, but it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2404 will only have a side effect if it is designed to have one.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2405 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2406 After evaluating the @code{set} expression, you can evaluate the symbol |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2407 @code{flowers} and it will return the value you just set. Here is the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2408 symbol. Place your cursor after it and type @kbd{C-x C-e}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2409 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2410 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2411 flowers |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2412 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2413 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2414 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2415 When you evaluate @code{flowers}, the list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2416 @code{(rose violet daisy buttercup)} appears in the echo area. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2417 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2418 Incidentally, if you evaluate @code{'flowers}, the variable with a quote |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2419 in front of it, what you will see in the echo area is the symbol itself, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2420 @code{flowers}. Here is the quoted symbol, so you can try this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2421 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2422 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2423 'flowers |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2424 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2425 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2426 Note also, that when you use @code{set}, you need to quote both |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2427 arguments to @code{set}, unless you want them evaluated. Since we do |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2428 not want either argument evaluated, neither the variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2429 @code{flowers} nor the list @code{(rose violet daisy buttercup)}, both |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2430 are quoted. (When you use @code{set} without quoting its first |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2431 argument, the first argument is evaluated before anything else is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2432 done. If you did this and @code{flowers} did not have a value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2433 already, you would get an error message that the @samp{Symbol's value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2434 as variable is void}; on the other hand, if @code{flowers} did return |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2435 a value after it was evaluated, the @code{set} would attempt to set |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2436 the value that was returned. There are situations where this is the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2437 right thing for the function to do; but such situations are rare.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2438 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2439 @node Using setq, Counting, Using set, set & setq |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2440 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2441 @subsection Using @code{setq} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2442 @findex setq |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2443 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2444 As a practical matter, you almost always quote the first argument to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2445 @code{set}. The combination of @code{set} and a quoted first argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2446 is so common that it has its own name: the special form @code{setq}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2447 This special form is just like @code{set} except that the first argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2448 is quoted automatically, so you don't need to type the quote mark |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2449 yourself. Also, as an added convenience, @code{setq} permits you to set |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2450 several different variables to different values, all in one expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2451 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2452 To set the value of the variable @code{carnivores} to the list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2453 @code{'(lion tiger leopard)} using @code{setq}, the following expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2454 is used: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2455 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2456 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2457 (setq carnivores '(lion tiger leopard)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2458 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2459 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2460 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2461 This is exactly the same as using @code{set} except the first argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2462 is automatically quoted by @code{setq}. (The @samp{q} in @code{setq} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2463 means @code{quote}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2464 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2465 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2466 With @code{set}, the expression would look like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2467 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2468 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2469 (set 'carnivores '(lion tiger leopard)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2470 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2471 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2472 Also, @code{setq} can be used to assign different values to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2473 different variables. The first argument is bound to the value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2474 of the second argument, the third argument is bound to the value of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2475 fourth argument, and so on. For example, you could use the following to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2476 assign a list of trees to the symbol @code{trees} and a list of herbivores |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2477 to the symbol @code{herbivores}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2478 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2479 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2480 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2481 (setq trees '(pine fir oak maple) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2482 herbivores '(gazelle antelope zebra)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2483 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2484 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2485 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2486 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2487 (The expression could just as well have been on one line, but it might |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2488 not have fit on a page; and humans find it easier to read nicely |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2489 formatted lists.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2490 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2491 Although I have been using the term `assign', there is another way of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2492 thinking about the workings of @code{set} and @code{setq}; and that is to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2493 say that @code{set} and @code{setq} make the symbol @emph{point} to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2494 list. This latter way of thinking is very common and in forthcoming |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2495 chapters we shall come upon at least one symbol that has `pointer' as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2496 part of its name. The name is chosen because the symbol has a value, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2497 specifically a list, attached to it; or, expressed another way, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2498 the symbol is set to ``point'' to the list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2499 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2500 @node Counting, , Using setq, set & setq |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2501 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2502 @subsection Counting |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2503 @cindex Counting |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2504 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2505 Here is an example that shows how to use @code{setq} in a counter. You |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2506 might use this to count how many times a part of your program repeats |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2507 itself. First set a variable to zero; then add one to the number each |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2508 time the program repeats itself. To do this, you need a variable that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2509 serves as a counter, and two expressions: an initial @code{setq} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2510 expression that sets the counter variable to zero; and a second |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2511 @code{setq} expression that increments the counter each time it is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2512 evaluated. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2513 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2514 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2515 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2516 (setq counter 0) ; @r{Let's call this the initializer.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2517 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2518 (setq counter (+ counter 1)) ; @r{This is the incrementer.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2519 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2520 counter ; @r{This is the counter.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2521 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2522 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2523 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2524 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2525 (The text following the @samp{;} are comments. @xref{Change a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2526 defun, , Change a Function Definition}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2527 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2528 If you evaluate the first of these expressions, the initializer, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2529 @code{(setq counter 0)}, and then evaluate the third expression, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2530 @code{counter}, the number @code{0} will appear in the echo area. If |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2531 you then evaluate the second expression, the incrementer, @code{(setq |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2532 counter (+ counter 1))}, the counter will get the value 1. So if you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2533 again evaluate @code{counter}, the number @code{1} will appear in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2534 echo area. Each time you evaluate the second expression, the value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2535 the counter will be incremented. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2536 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2537 When you evaluate the incrementer, @code{(setq counter (+ counter 1))}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2538 the Lisp interpreter first evaluates the innermost list; this is the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2539 addition. In order to evaluate this list, it must evaluate the variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2540 @code{counter} and the number @code{1}. When it evaluates the variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2541 @code{counter}, it receives its current value. It passes this value and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2542 the number @code{1} to the @code{+} which adds them together. The sum |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2543 is then returned as the value of the inner list and passed to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2544 @code{setq} which sets the variable @code{counter} to this new value. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2545 Thus, the value of the variable, @code{counter}, is changed. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2546 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2547 @node Summary, Error Message Exercises, set & setq, List Processing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2548 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2549 @section Summary |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2550 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2551 Learning Lisp is like climbing a hill in which the first part is the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2552 steepest. You have now climbed the most difficult part; what remains |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2553 becomes easier as you progress onwards. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2554 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2555 In summary, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2556 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2557 @itemize @bullet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2558 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2559 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2560 Lisp programs are made up of expressions, which are lists or single atoms. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2561 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2562 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2563 Lists are made up of zero or more atoms or inner lists, separated by whitespace and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2564 surrounded by parentheses. A list can be empty. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2565 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2566 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2567 Atoms are multi-character symbols, like @code{forward-paragraph}, single |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2568 character symbols like @code{+}, strings of characters between double |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2569 quotation marks, or numbers. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2570 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2571 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2572 A number evaluates to itself. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2573 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2574 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2575 A string between double quotes also evaluates to itself. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2576 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2577 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2578 When you evaluate a symbol by itself, its value is returned. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2579 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2580 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2581 When you evaluate a list, the Lisp interpreter looks at the first symbol |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2582 in the list and then at the function definition bound to that symbol. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2583 Then the instructions in the function definition are carried out. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2584 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2585 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2586 A single-quote, @code{'}, tells the Lisp interpreter that it should |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2587 return the following expression as written, and not evaluate it as it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2588 would if the quote were not there. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2589 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2590 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2591 Arguments are the information passed to a function. The arguments to a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2592 function are computed by evaluating the rest of the elements of the list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2593 of which the function is the first element. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2594 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2595 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2596 A function always returns a value when it is evaluated (unless it gets |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2597 an error); in addition, it may also carry out some action called a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2598 ``side effect''. In many cases, a function's primary purpose is to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2599 create a side effect. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2600 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2601 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2602 @node Error Message Exercises, , Summary, List Processing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2603 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2604 @section Exercises |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2605 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2606 A few simple exercises: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2607 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2608 @itemize @bullet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2609 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2610 Generate an error message by evaluating an appropriate symbol that is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2611 not within parentheses. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2612 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2613 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2614 Generate an error message by evaluating an appropriate symbol that is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2615 between parentheses. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2616 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2617 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2618 Create a counter that increments by two rather than one. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2619 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2620 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2621 Write an expression that prints a message in the echo area when |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2622 evaluated. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2623 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2624 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2625 @node Practicing Evaluation, Writing Defuns, List Processing, Top |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2626 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2627 @chapter Practicing Evaluation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2628 @cindex Practicing evaluation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2629 @cindex Evaluation practice |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2630 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2631 Before learning how to write a function definition in Emacs Lisp, it is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2632 useful to spend a little time evaluating various expressions that have |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2633 already been written. These expressions will be lists with the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2634 functions as their first (and often only) element. Since some of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2635 functions associated with buffers are both simple and interesting, we |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2636 will start with those. In this section, we will evaluate a few of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2637 these. In another section, we will study the code of several other |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2638 buffer-related functions, to see how they were written. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2639 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2640 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2641 * How to Evaluate:: Typing editing commands or @kbd{C-x C-e} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2642 causes evaluation. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2643 * Buffer Names:: Buffers and files are different. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2644 * Getting Buffers:: Getting a buffer itself, not merely its name. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2645 * Switching Buffers:: How to change to another buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2646 * Buffer Size & Locations:: Where point is located and the size of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2647 the buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2648 * Evaluation Exercise:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2649 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2650 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2651 @node How to Evaluate, Buffer Names, Practicing Evaluation, Practicing Evaluation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2652 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2653 @unnumberedsec How to Evaluate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2654 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2655 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2656 @i{Whenever you give an editing command} to Emacs Lisp, such as the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2657 command to move the cursor or to scroll the screen, @i{you are evaluating |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2658 an expression,} the first element of which is a function. @i{This is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2659 how Emacs works.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2660 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2661 @cindex @samp{interactive function} defined |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2662 @cindex @samp{command} defined |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2663 When you type keys, you cause the Lisp interpreter to evaluate an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2664 expression and that is how you get your results. Even typing plain text |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2665 involves evaluating an Emacs Lisp function, in this case, one that uses |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2666 @code{self-insert-command}, which simply inserts the character you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2667 typed. The functions you evaluate by typing keystrokes are called |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2668 @dfn{interactive} functions, or @dfn{commands}; how you make a function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2669 interactive will be illustrated in the chapter on how to write function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2670 definitions. @xref{Interactive, , Making a Function Interactive}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2671 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2672 In addition to typing keyboard commands, we have seen a second way to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2673 evaluate an expression: by positioning the cursor after a list and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2674 typing @kbd{C-x C-e}. This is what we will do in the rest of this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2675 section. There are other ways to evaluate an expression as well; these |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2676 will be described as we come to them. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2677 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2678 Besides being used for practicing evaluation, the functions shown in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2679 next few sections are important in their own right. A study of these |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2680 functions makes clear the distinction between buffers and files, how to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2681 switch to a buffer, and how to determine a location within it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2682 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2683 @node Buffer Names, Getting Buffers, How to Evaluate, Practicing Evaluation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2684 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2685 @section Buffer Names |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2686 @findex buffer-name |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2687 @findex buffer-file-name |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2688 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2689 The two functions, @code{buffer-name} and @code{buffer-file-name}, show |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2690 the difference between a file and a buffer. When you evaluate the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2691 following expression, @code{(buffer-name)}, the name of the buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2692 appears in the echo area. When you evaluate @code{(buffer-file-name)}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2693 the name of the file to which the buffer refers appears in the echo |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2694 area. Usually, the name returned by @code{(buffer-name)} is the same as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2695 the name of the file to which it refers, and the name returned by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2696 @code{(buffer-file-name)} is the full path-name of the file. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2697 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2698 A file and a buffer are two different entities. A file is information |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2699 recorded permanently in the computer (unless you delete it). A buffer, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2700 on the other hand, is information inside of Emacs that will vanish at |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2701 the end of the editing session (or when you kill the buffer). Usually, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2702 a buffer contains information that you have copied from a file; we say |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2703 the buffer is @dfn{visiting} that file. This copy is what you work on |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2704 and modify. Changes to the buffer do not change the file, until you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2705 save the buffer. When you save the buffer, the buffer is copied to the file |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2706 and is thus saved permanently. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2707 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2708 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2709 If you are reading this in Info inside of GNU Emacs, you can evaluate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2710 each of the following expressions by positioning the cursor after it and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2711 typing @kbd{C-x C-e}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2712 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2713 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2714 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2715 (buffer-name) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2716 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2717 (buffer-file-name) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2718 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2719 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2720 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2721 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2722 When I do this, @file{"introduction.texinfo"} is the value returned by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2723 evaluating @code{(buffer-name)}, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2724 @file{"/gnu/work/intro/introduction.texinfo"} is the value returned by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2725 evaluating @code{(buffer-file-name)}. The former is the name of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2726 buffer and the latter is the name of the file. (In the expressions, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2727 parentheses tell the Lisp interpreter to treat @code{buffer-name} and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2728 @code{buffer-file-name} as functions; without the parentheses, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2729 interpreter would attempt to evaluate the symbols as variables. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2730 @xref{Variables}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2731 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2732 In spite of the distinction between files and buffers, you will often |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2733 find that people refer to a file when they mean a buffer and vice-versa. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2734 Indeed, most people say, ``I am editing a file,'' rather than saying, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2735 ``I am editing a buffer which I will soon save to a file.'' It is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2736 almost always clear from context what people mean. When dealing with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2737 computer programs, however, it is important to keep the distinction in mind, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2738 since the computer is not as smart as a person. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2739 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2740 @cindex Buffer, history of word |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2741 The word `buffer', by the way, comes from the meaning of the word as a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2742 cushion that deadens the force of a collision. In early computers, a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2743 buffer cushioned the interaction between files and the computer's |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2744 central processing unit. The drums or tapes that held a file and the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2745 central processing unit were pieces of equipment that were very |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2746 different from each other, working at their own speeds, in spurts. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2747 buffer made it possible for them to work together effectively. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2748 Eventually, the buffer grew from being an intermediary, a temporary |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2749 holding place, to being the place where work is done. This |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2750 transformation is rather like that of a small seaport that grew into a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2751 great city: once it was merely the place where cargo was warehoused |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2752 temporarily before being loaded onto ships; then it became a business |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2753 and cultural center in its own right. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2754 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2755 Not all buffers are associated with files. For example, when you start |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2756 an Emacs session by typing the command @code{emacs} alone, without |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2757 naming any files, Emacs will start with the @file{*scratch*} buffer on |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2758 the screen. This buffer is not visiting any file. Similarly, a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2759 @file{*Help*} buffer is not associated with any file. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2760 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2761 @cindex @code{nil}, history of word |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2762 If you switch to the @file{*scratch*} buffer, type @code{(buffer-name)}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2763 position the cursor after it, and type @kbd{C-x C-e} to evaluate the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2764 expression, the name @code{"*scratch*"} is returned and will appear in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2765 the echo area. @code{"*scratch*"} is the name of the buffer. However, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2766 if you type @code{(buffer-file-name)} in the @file{*scratch*} buffer and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2767 evaluate that, @code{nil} will appear in the echo area. @code{nil} is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2768 from the Latin word for `nothing'; in this case, it means that the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2769 @file{*scratch*} buffer is not associated with any file. (In Lisp, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2770 @code{nil} is also used to mean `false' and is a synonym for the empty |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2771 list, @code{()}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2772 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2773 Incidentally, if you are in the @file{*scratch*} buffer and want the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2774 value returned by an expression to appear in the @file{*scratch*} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2775 buffer itself rather than in the echo area, type @kbd{C-u C-x C-e} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2776 instead of @kbd{C-x C-e}. This causes the value returned to appear |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2777 after the expression. The buffer will look like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2778 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2779 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2780 (buffer-name)"*scratch*" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2781 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2782 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2783 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2784 You cannot do this in Info since Info is read-only and it will not allow |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2785 you to change the contents of the buffer. But you can do this in any |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2786 buffer you can edit; and when you write code or documentation (such as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2787 this book), this feature is very useful. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2788 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2789 @node Getting Buffers, Switching Buffers, Buffer Names, Practicing Evaluation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2790 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2791 @section Getting Buffers |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2792 @findex current-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2793 @findex other-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2794 @cindex Getting a buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2795 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2796 The @code{buffer-name} function returns the @emph{name} of the buffer; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2797 to get the buffer @emph{itself}, a different function is needed: the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2798 @code{current-buffer} function. If you use this function in code, what |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2799 you get is the buffer itself. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2801 A name and the object or entity to which the name refers are different |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2802 from each other. You are not your name. You are a person to whom |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2803 others refer by name. If you ask to speak to George and someone hands you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2804 a card with the letters @samp{G}, @samp{e}, @samp{o}, @samp{r}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2805 @samp{g}, and @samp{e} written on it, you might be amused, but you would |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2806 not be satisfied. You do not want to speak to the name, but to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2807 person to whom the name refers. A buffer is similar: the name of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2808 scratch buffer is @file{*scratch*}, but the name is not the buffer. To |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2809 get a buffer itself, you need to use a function such as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2810 @code{current-buffer}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2811 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2812 However, there is a slight complication: if you evaluate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2813 @code{current-buffer} in an expression on its own, as we will do here, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2814 what you see is a printed representation of the name of the buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2815 without the contents of the buffer. Emacs works this way for two |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2816 reasons: the buffer may be thousands of lines long---too long to be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2817 conveniently displayed; and, another buffer may have the same contents |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2818 but a different name, and it is important to distinguish between them. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2819 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2820 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2821 Here is an expression containing the function: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2822 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2823 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2824 (current-buffer) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2825 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2826 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2827 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2828 If you evaluate the expression in the usual way, @file{#<buffer *info*>} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2829 appears in the echo area. The special format indicates that the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2830 buffer itself is being returned, rather than just its name. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2831 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2832 Incidentally, while you can type a number or symbol into a program, you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2833 cannot do that with the printed representation of a buffer: the only way |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2834 to get a buffer itself is with a function such as @code{current-buffer}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2835 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2836 A related function is @code{other-buffer}. This returns the most |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2837 recently selected buffer other than the one you are in currently. If |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2838 you have recently switched back and forth from the @file{*scratch*} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2839 buffer, @code{other-buffer} will return that buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2840 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2841 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2842 You can see this by evaluating the expression: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2843 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2844 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2845 (other-buffer) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2846 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2847 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2848 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2849 You should see @file{#<buffer *scratch*>} appear in the echo area, or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2850 the name of whatever other buffer you switched back from most |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2851 recently@footnote{Actually, by default, if the buffer from which you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2852 just switched is visible to you in another window, @code{other-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2853 will choose the most recent buffer that you cannot see; this is a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2854 subtlety that I often forget.}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2855 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2856 @node Switching Buffers, Buffer Size & Locations, Getting Buffers, Practicing Evaluation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2857 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2858 @section Switching Buffers |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2859 @findex switch-to-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2860 @findex set-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2861 @cindex Switching to a buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2862 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2863 The @code{other-buffer} function actually provides a buffer when it is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2864 used as an argument to a function that requires one. We can see this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2865 by using @code{other-buffer} and @code{switch-to-buffer} to switch to a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2866 different buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2867 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2868 But first, a brief introduction to the @code{switch-to-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2869 function. When you switched back and forth from Info to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2870 @file{*scratch*} buffer to evaluate @code{(buffer-name)}, you most |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2871 likely typed @kbd{C-x b} and then typed @file{*scratch*}@footnote{Or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2872 rather, to save typing, you probably typed just part of the name, such |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2873 as @code{*sc}, and then pressed your @kbd{TAB} key to cause it to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2874 expand to the full name; and then typed your @kbd{RET} key.} when |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2875 prompted in the minibuffer for the name of the buffer to which you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2876 wanted to switch. The keystrokes, @kbd{C-x b}, cause the Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2877 interpreter to evaluate the interactive function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2878 @code{switch-to-buffer}. As we said before, this is how Emacs works: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2879 different keystrokes call or run different functions. For example, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2880 @kbd{C-f} calls @code{forward-char}, @kbd{M-e} calls |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2881 @code{forward-sentence}, and so on. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2882 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2883 By writing @code{switch-to-buffer} in an expression, and giving it a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2884 buffer to switch to, we can switch buffers just the way @kbd{C-x b} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2885 does. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2886 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2887 @need 1000 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2888 Here is the Lisp expression: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2889 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2890 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2891 (switch-to-buffer (other-buffer)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2892 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2893 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2894 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2895 The symbol @code{switch-to-buffer} is the first element of the list, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2896 so the Lisp interpreter will treat it as a function and carry out the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2897 instructions that are attached to it. But before doing that, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2898 interpreter will note that @code{other-buffer} is inside parentheses |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2899 and work on that symbol first. @code{other-buffer} is the first (and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2900 in this case, the only) element of this list, so the Lisp interpreter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2901 calls or runs the function. It returns another buffer. Next, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2902 interpreter runs @code{switch-to-buffer}, passing to it, as an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2903 argument, the other buffer, which is what Emacs will switch to. If |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2904 you are reading this in Info, try this now. Evaluate the expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2905 (To get back, type @kbd{C-x b @key{RET}}.)@footnote{Remember, this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2906 expression will move you to your most recent other buffer that you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2907 cannot see. If you really want to go to your most recently selected |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2908 buffer, even if you can still see it, you need to evaluate the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2909 following more complex expression: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2910 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2911 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2912 (switch-to-buffer (other-buffer (current-buffer) t)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2913 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2914 |
42562
fb149efd0c72
Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents:
42506
diff
changeset
|
2915 @c noindent |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2916 In this case, the first argument to @code{other-buffer} tells it which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2917 buffer to skip---the current one---and the second argument tells |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2918 @code{other-buffer} it is OK to switch to a visible buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2919 In regular use, @code{switch-to-buffer} takes you to an invisible |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2920 window since you would most likely use @kbd{C-x o} (@code{other-window}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2921 to go to another visible buffer.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2922 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2923 In the programming examples in later sections of this document, you will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2924 see the function @code{set-buffer} more often than |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2925 @code{switch-to-buffer}. This is because of a difference between |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2926 computer programs and humans: humans have eyes and expect to see the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2927 buffer on which they are working on their computer terminals. This is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2928 so obvious, it almost goes without saying. However, programs do not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2929 have eyes. When a computer program works on a buffer, that buffer does |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2930 not need to be visible on the screen. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2931 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2932 @code{switch-to-buffer} is designed for humans and does two different |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2933 things: it switches the buffer to which Emacs' attention is directed; and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2934 it switches the buffer displayed in the window to the new buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2935 @code{set-buffer}, on the other hand, does only one thing: it switches |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2936 the attention of the computer program to a different buffer. The buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2937 on the screen remains unchanged (of course, normally nothing happens |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2938 there until the command finishes running). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2939 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2940 @cindex @samp{call} defined |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2941 Also, we have just introduced another jargon term, the word @dfn{call}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2942 When you evaluate a list in which the first symbol is a function, you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2943 are calling that function. The use of the term comes from the notion of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2944 the function as an entity that can do something for you if you `call' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2945 it---just as a plumber is an entity who can fix a leak if you call him |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2946 or her. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2947 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2948 @node Buffer Size & Locations, Evaluation Exercise, Switching Buffers, Practicing Evaluation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2949 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2950 @section Buffer Size and the Location of Point |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2951 @cindex Size of buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2952 @cindex Buffer size |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2953 @cindex Point location |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2954 @cindex Location of point |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2955 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2956 Finally, let's look at several rather simple functions, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2957 @code{buffer-size}, @code{point}, @code{point-min}, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2958 @code{point-max}. These give information about the size of a buffer and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2959 the location of point within it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2960 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2961 The function @code{buffer-size} tells you the size of the current |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2962 buffer; that is, the function returns a count of the number of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2963 characters in the buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2964 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2965 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2966 (buffer-size) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2967 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2968 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2969 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2970 You can evaluate this in the usual way, by positioning the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2971 cursor after the expression and typing @kbd{C-x C-e}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2972 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2973 @cindex @samp{point} defined |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2974 In Emacs, the current position of the cursor is called @dfn{point}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2975 The expression @code{(point)} returns a number that tells you where the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2976 cursor is located as a count of the number of characters from the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2977 beginning of the buffer up to point. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2978 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2979 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2980 You can see the character count for point in this buffer by evaluating |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2981 the following expression in the usual way: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2982 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2983 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2984 (point) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2985 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2986 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2987 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2988 As I write this, the value of @code{point} is 65724. The @code{point} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2989 function is frequently used in some of the examples later in this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2990 book. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2991 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2992 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2993 The value of point depends, of course, on its location within the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2994 buffer. If you evaluate point in this spot, the number will be larger: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2995 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2996 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2997 (point) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2998 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
2999 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3000 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3001 For me, the value of point in this location is 66043, which means that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3002 there are 319 characters (including spaces) between the two expressions. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3003 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3004 @cindex @samp{narrowing} defined |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3005 The function @code{point-min} is somewhat similar to @code{point}, but |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3006 it returns the value of the minimum permissible value of point in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3007 current buffer. This is the number 1 unless @dfn{narrowing} is in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3008 effect. (Narrowing is a mechanism whereby you can restrict yourself, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3009 or a program, to operations on just a part of a buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3010 @xref{Narrowing & Widening, , Narrowing and Widening}.) Likewise, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3011 function @code{point-max} returns the value of the maximum permissible |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3012 value of point in the current buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3013 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3014 @node Evaluation Exercise, , Buffer Size & Locations, Practicing Evaluation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3015 @section Exercise |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3016 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3017 Find a file with which you are working and move towards its middle. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3018 Find its buffer name, file name, length, and your position in the file. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3019 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3020 @node Writing Defuns, Buffer Walk Through, Practicing Evaluation, Top |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3021 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3022 @chapter How To Write Function Definitions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3023 @cindex Definition writing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3024 @cindex Function definition writing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3025 @cindex Writing a function definition |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3026 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3027 When the Lisp interpreter evaluates a list, it looks to see whether the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3028 first symbol on the list has a function definition attached to it; or, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3029 put another way, whether the symbol points to a function definition. If |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3030 it does, the computer carries out the instructions in the definition. A |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3031 symbol that has a function definition is called, simply, a function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3032 (although, properly speaking, the definition is the function and the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3033 symbol refers to it.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3034 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3035 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3036 * Primitive Functions:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3037 * defun:: The @code{defun} special form. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3038 * Install:: Install a function definition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3039 * Interactive:: Making a function interactive. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3040 * Interactive Options:: Different options for @code{interactive}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3041 * Permanent Installation:: Installing code permanently. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3042 * let:: Creating and initializing local variables. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3043 * if:: What if? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3044 * else:: If--then--else expressions. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3045 * Truth & Falsehood:: What Lisp considers false and true. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3046 * save-excursion:: Keeping track of point, mark, and buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3047 * Review:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3048 * defun Exercises:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3049 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3050 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3051 @node Primitive Functions, defun, Writing Defuns, Writing Defuns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3052 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3053 @unnumberedsec An Aside about Primitive Functions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3054 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3055 @cindex Primitive functions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3056 @cindex Functions, primitive |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3057 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3058 @cindex C language primitives |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3059 @cindex Primitives written in C |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3060 All functions are defined in terms of other functions, except for a few |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3061 @dfn{primitive} functions that are written in the C programming |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3062 language. When you write functions' definitions, you will write them in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3063 Emacs Lisp and use other functions as your building blocks. Some of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3064 functions you will use will themselves be written in Emacs Lisp (perhaps |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3065 by you) and some will be primitives written in C. The primitive |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3066 functions are used exactly like those written in Emacs Lisp and behave |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3067 like them. They are written in C so we can easily run GNU Emacs on any |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3068 computer that has sufficient power and can run C. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3069 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3070 Let me re-emphasize this: when you write code in Emacs Lisp, you do not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3071 distinguish between the use of functions written in C and the use of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3072 functions written in Emacs Lisp. The difference is irrelevant. I |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3073 mention the distinction only because it is interesting to know. Indeed, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3074 unless you investigate, you won't know whether an already-written |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3075 function is written in Emacs Lisp or C. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3076 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3077 @node defun, Install, Primitive Functions, Writing Defuns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3078 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3079 @section The @code{defun} Special Form |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3080 @findex defun |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3081 @cindex Special form of @code{defun} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3082 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3083 @cindex @samp{function definition} defined |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3084 In Lisp, a symbol such as @code{mark-whole-buffer} has code attached to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3085 it that tells the computer what to do when the function is called. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3086 This code is called the @dfn{function definition} and is created by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3087 evaluating a Lisp expression that starts with the symbol @code{defun} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3088 (which is an abbreviation for @emph{define function}). Because |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3089 @code{defun} does not evaluate its arguments in the usual way, it is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3090 called a @dfn{special form}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3091 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3092 In subsequent sections, we will look at function definitions from the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3093 Emacs source code, such as @code{mark-whole-buffer}. In this section, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3094 we will describe a simple function definition so you can see how it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3095 looks. This function definition uses arithmetic because it makes for a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3096 simple example. Some people dislike examples using arithmetic; however, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3097 if you are such a person, do not despair. Hardly any of the code we |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3098 will study in the remainder of this introduction involves arithmetic or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3099 mathematics. The examples mostly involve text in one way or another. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3100 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3101 A function definition has up to five parts following the word |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3102 @code{defun}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3103 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3104 @enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3105 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3106 The name of the symbol to which the function definition should be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3107 attached. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3108 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3109 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3110 A list of the arguments that will be passed to the function. If no |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3111 arguments will be passed to the function, this is an empty list, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3112 @code{()}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3113 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3114 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3115 Documentation describing the function. (Technically optional, but |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3116 strongly recommended.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3117 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3118 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3119 Optionally, an expression to make the function interactive so you can |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3120 use it by typing @kbd{M-x} and then the name of the function; or by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3121 typing an appropriate key or keychord. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3122 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3123 @cindex @samp{body} defined |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3124 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3125 The code that instructs the computer what to do: the @dfn{body} of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3126 function definition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3127 @end enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3128 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3129 It is helpful to think of the five parts of a function definition as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3130 being organized in a template, with slots for each part: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3131 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3132 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3133 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3134 (defun @var{function-name} (@var{arguments}@dots{}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3135 "@var{optional-documentation}@dots{}" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3136 (interactive @var{argument-passing-info}) ; @r{optional} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3137 @var{body}@dots{}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3138 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3139 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3140 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3141 As an example, here is the code for a function that multiplies its |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3142 argument by 7. (This example is not interactive. @xref{Interactive, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3143 , Making a Function Interactive}, for that information.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3144 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3145 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3146 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3147 (defun multiply-by-seven (number) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3148 "Multiply NUMBER by seven." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3149 (* 7 number)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3150 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3151 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3152 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3153 This definition begins with a parenthesis and the symbol @code{defun}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3154 followed by the name of the function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3155 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3156 @cindex @samp{argument list} defined |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3157 The name of the function is followed by a list that contains the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3158 arguments that will be passed to the function. This list is called |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3159 the @dfn{argument list}. In this example, the list has only one |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3160 element, the symbol, @code{number}. When the function is used, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3161 symbol will be bound to the value that is used as the argument to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3162 function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3163 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3164 Instead of choosing the word @code{number} for the name of the argument, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3165 I could have picked any other name. For example, I could have chosen |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3166 the word @code{multiplicand}. I picked the word `number' because it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3167 tells what kind of value is intended for this slot; but I could just as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3168 well have chosen the word `multiplicand' to indicate the role that the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3169 value placed in this slot will play in the workings of the function. I |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3170 could have called it @code{foogle}, but that would have been a bad |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3171 choice because it would not tell humans what it means. The choice of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3172 name is up to the programmer and should be chosen to make the meaning of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3173 the function clear. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3174 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3175 Indeed, you can choose any name you wish for a symbol in an argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3176 list, even the name of a symbol used in some other function: the name |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3177 you use in an argument list is private to that particular definition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3178 In that definition, the name refers to a different entity than any use |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3179 of the same name outside the function definition. Suppose you have a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3180 nick-name `Shorty' in your family; when your family members refer to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3181 `Shorty', they mean you. But outside your family, in a movie, for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3182 example, the name `Shorty' refers to someone else. Because a name in an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3183 argument list is private to the function definition, you can change the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3184 value of such a symbol inside the body of a function without changing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3185 its value outside the function. The effect is similar to that produced |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3186 by a @code{let} expression. (@xref{let, , @code{let}}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3187 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3188 @ignore |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3189 Note also that we discuss the word `number' in two different ways: as a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3190 symbol that appears in the code, and as the name of something that will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3191 be replaced by a something else during the evaluation of the function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3192 In the first case, @code{number} is a symbol, not a number; it happens |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3193 that within the function, it is a variable who value is the number in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3194 question, but our primary interest in it is as a symbol. On the other |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3195 hand, when we are talking about the function, our interest is that we |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3196 will substitute a number for the word @var{number}. To keep this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3197 distinction clear, we use different typography for the two |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3198 circumstances. When we talk about this function, or about how it works, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3199 we refer to this number by writing @var{number}. In the function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3200 itself, we refer to it by writing @code{number}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3201 @end ignore |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3202 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3203 The argument list is followed by the documentation string that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3204 describes the function. This is what you see when you type |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3205 @w{@kbd{C-h f}} and the name of a function. Incidentally, when you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3206 write a documentation string like this, you should make the first line |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3207 a complete sentence since some commands, such as @code{apropos}, print |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3208 only the first line of a multi-line documentation string. Also, you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3209 should not indent the second line of a documentation string, if you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3210 have one, because that looks odd when you use @kbd{C-h f} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3211 (@code{describe-function}). The documentation string is optional, but |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3212 it is so useful, it should be included in almost every function you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3213 write. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3214 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3215 @findex * @r{(multiplication)} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3216 The third line of the example consists of the body of the function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3217 definition. (Most functions' definitions, of course, are longer than |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3218 this.) In this function, the body is the list, @code{(* 7 number)}, which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3219 says to multiply the value of @var{number} by 7. (In Emacs Lisp, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3220 @code{*} is the function for multiplication, just as @code{+} is the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3221 function for addition.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3222 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3223 When you use the @code{multiply-by-seven} function, the argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3224 @code{number} evaluates to the actual number you want used. Here is an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3225 example that shows how @code{multiply-by-seven} is used; but don't try |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3226 to evaluate this yet! |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3227 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3228 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3229 (multiply-by-seven 3) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3230 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3231 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3232 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3233 The symbol @code{number}, specified in the function definition in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3234 next section, is given or ``bound to'' the value 3 in the actual use of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3235 the function. Note that although @code{number} was inside parentheses |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3236 in the function definition, the argument passed to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3237 @code{multiply-by-seven} function is not in parentheses. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3238 parentheses are written in the function definition so the computer can |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3239 figure out where the argument list ends and the rest of the function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3240 definition begins. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3241 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3242 If you evaluate this example, you are likely to get an error message. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3243 (Go ahead, try it!) This is because we have written the function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3244 definition, but not yet told the computer about the definition---we have |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3245 not yet installed (or `loaded') the function definition in Emacs. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3246 Installing a function is the process that tells the Lisp interpreter the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3247 definition of the function. Installation is described in the next |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3248 section. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3249 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3250 @node Install, Interactive, defun, Writing Defuns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3251 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3252 @section Install a Function Definition |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3253 @cindex Install a Function Definition |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3254 @cindex Definition installation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3255 @cindex Function definition installation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3256 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3257 If you are reading this inside of Info in Emacs, you can try out the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3258 @code{multiply-by-seven} function by first evaluating the function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3259 definition and then evaluating @code{(multiply-by-seven 3)}. A copy of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3260 the function definition follows. Place the cursor after the last |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3261 parenthesis of the function definition and type @kbd{C-x C-e}. When you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3262 do this, @code{multiply-by-seven} will appear in the echo area. (What |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3263 this means is that when a function definition is evaluated, the value it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3264 returns is the name of the defined function.) At the same time, this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3265 action installs the function definition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3266 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3267 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3268 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3269 (defun multiply-by-seven (number) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3270 "Multiply NUMBER by seven." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3271 (* 7 number)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3272 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3273 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3274 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3275 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3276 By evaluating this @code{defun}, you have just installed |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3277 @code{multiply-by-seven} in Emacs. The function is now just as much a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3278 part of Emacs as @code{forward-word} or any other editing function you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3279 use. (@code{multiply-by-seven} will stay installed until you quit |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3280 Emacs. To reload code automatically whenever you start Emacs, see |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3281 @ref{Permanent Installation, , Installing Code Permanently}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3282 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3283 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3284 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3285 * Effect of installation:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3286 * Change a defun:: How to change a function definition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3287 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3288 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3289 @node Effect of installation, Change a defun, Install, Install |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3290 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3291 @unnumberedsubsec The effect of installation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3292 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3293 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3294 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3295 You can see the effect of installing @code{multiply-by-seven} by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3296 evaluating the following sample. Place the cursor after the following |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3297 expression and type @kbd{C-x C-e}. The number 21 will appear in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3298 echo area. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3299 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3300 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3301 (multiply-by-seven 3) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3302 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3303 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3304 If you wish, you can read the documentation for the function by typing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3305 @kbd{C-h f} (@code{describe-function}) and then the name of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3306 function, @code{multiply-by-seven}. When you do this, a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3307 @file{*Help*} window will appear on your screen that says: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3308 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3309 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3310 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3311 multiply-by-seven: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3312 Multiply NUMBER by seven. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3313 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3314 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3315 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3316 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3317 (To return to a single window on your screen, type @kbd{C-x 1}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3318 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3319 @node Change a defun, , Effect of installation, Install |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3320 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3321 @subsection Change a Function Definition |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3322 @cindex Changing a function definition |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3323 @cindex Function definition, how to change |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3324 @cindex Definition, how to change |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3325 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3326 If you want to change the code in @code{multiply-by-seven}, just rewrite |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3327 it. To install the new version in place of the old one, evaluate the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3328 function definition again. This is how you modify code in Emacs. It is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3329 very simple. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3330 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3331 As an example, you can change the @code{multiply-by-seven} function to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3332 add the number to itself seven times instead of multiplying the number |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3333 by seven. It produces the same answer, but by a different path. At |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3334 the same time, we will add a comment to the code; a comment is text |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3335 that the Lisp interpreter ignores, but that a human reader may find |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3336 useful or enlightening. The comment is that this is the ``second |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3337 version''. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3338 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3339 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3340 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3341 (defun multiply-by-seven (number) ; @r{Second version.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3342 "Multiply NUMBER by seven." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3343 (+ number number number number number number number)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3344 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3345 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3346 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3347 @cindex Comments in Lisp code |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3348 The comment follows a semicolon, @samp{;}. In Lisp, everything on a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3349 line that follows a semicolon is a comment. The end of the line is the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3350 end of the comment. To stretch a comment over two or more lines, begin |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3351 each line with a semicolon. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3352 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3353 @xref{Beginning a .emacs File, , Beginning a @file{.emacs} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3354 File}, and @ref{Comments, , Comments, elisp, The GNU Emacs Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3355 Reference Manual}, for more about comments. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3356 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3357 You can install this version of the @code{multiply-by-seven} function by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3358 evaluating it in the same way you evaluated the first function: place |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3359 the cursor after the last parenthesis and type @kbd{C-x C-e}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3360 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3361 In summary, this is how you write code in Emacs Lisp: you write a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3362 function; install it; test it; and then make fixes or enhancements and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3363 install it again. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3364 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3365 @node Interactive, Interactive Options, Install, Writing Defuns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3366 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3367 @section Make a Function Interactive |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3368 @cindex Interactive functions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3369 @findex interactive |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3370 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3371 You make a function interactive by placing a list that begins with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3372 the special form @code{interactive} immediately after the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3373 documentation. A user can invoke an interactive function by typing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3374 @kbd{M-x} and then the name of the function; or by typing the keys to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3375 which it is bound, for example, by typing @kbd{C-n} for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3376 @code{next-line} or @kbd{C-x h} for @code{mark-whole-buffer}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3377 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3378 Interestingly, when you call an interactive function interactively, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3379 the value returned is not automatically displayed in the echo area. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3380 This is because you often call an interactive function for its side |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3381 effects, such as moving forward by a word or line, and not for the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3382 value returned. If the returned value were displayed in the echo area |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3383 each time you typed a key, it would be very distracting. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3384 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3385 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3386 * Interactive multiply-by-seven:: An overview. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3387 * multiply-by-seven in detail:: The interactive version. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3388 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3389 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3390 @node Interactive multiply-by-seven, multiply-by-seven in detail, Interactive, Interactive |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3391 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3392 @unnumberedsubsec An Interactive @code{multiply-by-seven}, An Overview |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3393 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3394 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3395 Both the use of the special form @code{interactive} and one way to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3396 display a value in the echo area can be illustrated by creating an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3397 interactive version of @code{multiply-by-seven}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3398 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3399 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3400 Here is the code: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3401 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3402 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3403 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3404 (defun multiply-by-seven (number) ; @r{Interactive version.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3405 "Multiply NUMBER by seven." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3406 (interactive "p") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3407 (message "The result is %d" (* 7 number))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3408 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3409 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3410 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3411 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3412 You can install this code by placing your cursor after it and typing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3413 @kbd{C-x C-e}. The name of the function will appear in your echo area. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3414 Then, you can use this code by typing @kbd{C-u} and a number and then |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3415 typing @kbd{M-x multiply-by-seven} and pressing @key{RET}. The phrase |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3416 @samp{The result is @dots{}} followed by the product will appear in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3417 echo area. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3418 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3419 Speaking more generally, you invoke a function like this in either of two |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3420 ways: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3421 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3422 @enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3423 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3424 By typing a prefix argument that contains the number to be passed, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3425 then typing @kbd{M-x} and the name of the function, as with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3426 @kbd{C-u 3 M-x forward-sentence}; or, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3427 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3428 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3429 By typing whatever key or keychord the function is bound to, as with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3430 @kbd{C-u 3 M-e}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3431 @end enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3432 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3433 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3434 Both the examples just mentioned work identically to move point forward |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3435 three sentences. (Since @code{multiply-by-seven} is not bound to a key, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3436 it could not be used as an example of key binding.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3437 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3438 (@xref{Keybindings, , Some Keybindings}, to learn how to bind a command |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3439 to a key.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3440 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3441 A prefix argument is passed to an interactive function by typing the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3442 @key{META} key followed by a number, for example, @kbd{M-3 M-e}, or by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3443 typing @kbd{C-u} and then a number, for example, @kbd{C-u 3 M-e} (if you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3444 type @kbd{C-u} without a number, it defaults to 4). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3445 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3446 @node multiply-by-seven in detail, , Interactive multiply-by-seven, Interactive |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3447 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3448 @subsection An Interactive @code{multiply-by-seven} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3449 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3450 Let's look at the use of the special form @code{interactive} and then at |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3451 the function @code{message} in the interactive version of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3452 @code{multiply-by-seven}. You will recall that the function definition |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3453 looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3454 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3455 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3456 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3457 (defun multiply-by-seven (number) ; @r{Interactive version.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3458 "Multiply NUMBER by seven." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3459 (interactive "p") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3460 (message "The result is %d" (* 7 number))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3461 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3462 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3463 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3464 In this function, the expression, @code{(interactive "p")}, is a list of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3465 two elements. The @code{"p"} tells Emacs to pass the prefix argument to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3466 the function and use its value for the argument of the function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3467 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3468 @need 1000 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3469 The argument will be a number. This means that the symbol |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3470 @code{number} will be bound to a number in the line: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3471 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3472 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3473 (message "The result is %d" (* 7 number)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3474 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3475 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3476 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3477 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3478 For example, if your prefix argument is 5, the Lisp interpreter will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3479 evaluate the line as if it were: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3480 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3481 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3482 (message "The result is %d" (* 7 5)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3483 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3484 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3485 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3486 (If you are reading this in GNU Emacs, you can evaluate this expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3487 yourself.) First, the interpreter will evaluate the inner list, which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3488 is @code{(* 7 5)}. This returns a value of 35. Next, it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3489 will evaluate the outer list, passing the values of the second and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3490 subsequent elements of the list to the function @code{message}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3491 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3492 As we have seen, @code{message} is an Emacs Lisp function especially |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3493 designed for sending a one line message to a user. (@xref{message, , The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3494 @code{message} function}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3495 In summary, the @code{message} function prints its first argument in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3496 echo area as is, except for occurrences of @samp{%d}, @samp{%s}, or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3497 @samp{%c}. When it sees one of these control sequences, the function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3498 looks to the second and subsequent arguments and prints the value of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3499 argument in the location in the string where the control sequence is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3500 located. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3501 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3502 In the interactive @code{multiply-by-seven} function, the control string |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3503 is @samp{%d}, which requires a number, and the value returned by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3504 evaluating @code{(* 7 5)} is the number 35. Consequently, the number 35 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3505 is printed in place of the @samp{%d} and the message is @samp{The result |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3506 is 35}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3507 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3508 (Note that when you call the function @code{multiply-by-seven}, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3509 message is printed without quotes, but when you call @code{message}, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3510 text is printed in double quotes. This is because the value returned by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3511 @code{message} is what appears in the echo area when you evaluate an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3512 expression whose first element is @code{message}; but when embedded in a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3513 function, @code{message} prints the text as a side effect without |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3514 quotes.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3515 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3516 @node Interactive Options, Permanent Installation, Interactive, Writing Defuns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3517 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3518 @section Different Options for @code{interactive} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3519 @cindex Options for @code{interactive} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3520 @cindex Interactive options |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3521 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3522 In the example, @code{multiply-by-seven} used @code{"p"} as the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3523 argument to @code{interactive}. This argument told Emacs to interpret |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3524 your typing either @kbd{C-u} followed by a number or @key{META} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3525 followed by a number as a command to pass that number to the function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3526 as its argument. Emacs has more than twenty characters predefined for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3527 use with @code{interactive}. In almost every case, one of these |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3528 options will enable you to pass the right information interactively to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3529 a function. (@xref{Interactive Codes, , Code Characters for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3530 @code{interactive}, elisp, The GNU Emacs Lisp Reference Manual}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3531 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3532 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3533 For example, the character @samp{r} causes Emacs to pass the beginning |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3534 and end of the region (the current values of point and mark) to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3535 function as two separate arguments. It is used as follows: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3536 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3537 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3538 (interactive "r") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3539 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3540 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3541 On the other hand, a @samp{B} tells Emacs to ask for the name of a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3542 buffer that will be passed to the function. When it sees a @samp{B}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3543 Emacs will ask for the name by prompting the user in the minibuffer, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3544 using a string that follows the @samp{B}, as in @code{"BAppend to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3545 buffer:@: "}. Not only will Emacs prompt for the name, but Emacs will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3546 complete the name if you type enough of it and press @key{TAB}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3547 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3548 A function with two or more arguments can have information passed to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3549 each argument by adding parts to the string that follows |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3550 @code{interactive}. When you do this, the information is passed to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3551 each argument in the same order it is specified in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3552 @code{interactive} list. In the string, each part is separated from |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3553 the next part by a @samp{\n}, which is a newline. For example, you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3554 could follow @code{"BAppend to buffer:@: "} with a @samp{\n}) and an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3555 @samp{r}. This would cause Emacs to pass the values of point and mark |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3556 to the function as well as prompt you for the buffer---three arguments |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3557 in all. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3558 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3559 In this case, the function definition would look like the following, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3560 where @code{buffer}, @code{start}, and @code{end} are the symbols to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3561 which @code{interactive} binds the buffer and the current values of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3562 beginning and ending of the region: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3563 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3564 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3565 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3566 (defun @var{name-of-function} (buffer start end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3567 "@var{documentation}@dots{}" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3568 (interactive "BAppend to buffer:@: \nr") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3569 @var{body-of-function}@dots{}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3570 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3571 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3572 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3573 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3574 (The space after the colon in the prompt makes it look better when you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3575 are prompted. The @code{append-to-buffer} function looks exactly like |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3576 this. @xref{append-to-buffer, , The Definition of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3577 @code{append-to-buffer}}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3578 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3579 If a function does not have arguments, then @code{interactive} does not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3580 require any. Such a function contains the simple expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3581 @code{(interactive)}. The @code{mark-whole-buffer} function is like |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3582 this. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3583 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3584 Alternatively, if the special letter-codes are not right for your |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3585 application, you can pass your own arguments to @code{interactive} as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3586 a list. @xref{interactive, , Using @code{Interactive}, elisp, The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3587 GNU Emacs Lisp Reference Manual}, for more information about this advanced |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3588 technique. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3589 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3590 @node Permanent Installation, let, Interactive Options, Writing Defuns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3591 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3592 @section Install Code Permanently |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3593 @cindex Install code permanently |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3594 @cindex Permanent code installation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3595 @cindex Code installation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3596 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3597 When you install a function definition by evaluating it, it will stay |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3598 installed until you quit Emacs. The next time you start a new session |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3599 of Emacs, the function will not be installed unless you evaluate the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3600 function definition again. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3601 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3602 At some point, you may want to have code installed automatically |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3603 whenever you start a new session of Emacs. There are several ways of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3604 doing this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3605 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3606 @itemize @bullet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3607 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3608 If you have code that is just for yourself, you can put the code for the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3609 function definition in your @file{.emacs} initialization file. When you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3610 start Emacs, your @file{.emacs} file is automatically evaluated and all |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3611 the function definitions within it are installed. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3612 @xref{Emacs Initialization, , Your @file{.emacs} File}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3613 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3614 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3615 Alternatively, you can put the function definitions that you want |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3616 installed in one or more files of their own and use the @code{load} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3617 function to cause Emacs to evaluate and thereby install each of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3618 functions in the files. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3619 @xref{Loading Files, , Loading Files}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3620 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3621 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3622 On the other hand, if you have code that your whole site will use, it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3623 is usual to put it in a file called @file{site-init.el} that is loaded |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3624 when Emacs is built. This makes the code available to everyone who |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3625 uses your machine. (See the @file{INSTALL} file that is part of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3626 Emacs distribution.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3627 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3628 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3629 Finally, if you have code that everyone who uses Emacs may want, you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3630 can post it on a computer network or send a copy to the Free Software |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3631 Foundation. (When you do this, please license the code and its |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3632 documentation under a license that permits other people to run, copy, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3633 study, modify, and redistribute the code and which protects you from |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3634 having your work taken from you.) If you send a copy of your code to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3635 the Free Software Foundation, and properly protect yourself and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3636 others, it may be included in the next release of Emacs. In large |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3637 part, this is how Emacs has grown over the past years, by donations. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3638 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3639 @node let, if, Permanent Installation, Writing Defuns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3640 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3641 @section @code{let} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3642 @findex let |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3643 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3644 The @code{let} expression is a special form in Lisp that you will need |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3645 to use in most function definitions. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3646 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3647 @code{let} is used to attach or bind a symbol to a value in such a way |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3648 that the Lisp interpreter will not confuse the variable with a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3649 variable of the same name that is not part of the function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3650 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3651 To understand why the @code{let} special form is necessary, consider |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3652 the situation in which you own a home that you generally refer to as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3653 `the house', as in the sentence, ``The house needs painting.'' If you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3654 are visiting a friend and your host refers to `the house', he is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3655 likely to be referring to @emph{his} house, not yours, that is, to a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3656 different house. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3657 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3658 If your friend is referring to his house and you think he is referring |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3659 to your house, you may be in for some confusion. The same thing could |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3660 happen in Lisp if a variable that is used inside of one function has |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3661 the same name as a variable that is used inside of another function, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3662 and the two are not intended to refer to the same value. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3663 @code{let} special form prevents this kind of confusion. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3664 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3665 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3666 * Prevent confusion:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3667 * Parts of let Expression:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3668 * Sample let Expression:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3669 * Uninitialized let Variables:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3670 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3671 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3672 @node Prevent confusion, Parts of let Expression, let, let |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3673 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3674 @unnumberedsubsec @code{let} Prevents Confusion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3675 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3676 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3677 @cindex @samp{local variable} defined |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3678 The @code{let} special form prevents confusion. @code{let} creates a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3679 name for a @dfn{local variable} that overshadows any use of the same |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3680 name outside the @code{let} expression. This is like understanding |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3681 that whenever your host refers to `the house', he means his house, not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3682 yours. (Symbols used in argument lists work the same way. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3683 @xref{defun, , The @code{defun} Special Form}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3684 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3685 Local variables created by a @code{let} expression retain their value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3686 @emph{only} within the @code{let} expression itself (and within |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3687 expressions called within the @code{let} expression); the local |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3688 variables have no effect outside the @code{let} expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3689 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3690 Another way to think about @code{let} is that it is like a @code{setq} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3691 that is temporary and local. The values set by @code{let} are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3692 automatically undone when the @code{let} is finished. The setting |
44899
ebddb2618c17
Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents:
43431
diff
changeset
|
3693 only affects expressions that are inside the bounds of the @code{let} |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3694 expression. In computer science jargon, we would say ``the binding of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3695 a symbol is visible only in functions called in the @code{let} form; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3696 in Emacs Lisp, scoping is dynamic, not lexical.'' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3697 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3698 @code{let} can create more than one variable at once. Also, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3699 @code{let} gives each variable it creates an initial value, either a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3700 value specified by you, or @code{nil}. (In the jargon, this is called |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3701 `binding the variable to the value'.) After @code{let} has created |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3702 and bound the variables, it executes the code in the body of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3703 @code{let}, and returns the value of the last expression in the body, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3704 as the value of the whole @code{let} expression. (`Execute' is a jargon |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3705 term that means to evaluate a list; it comes from the use of the word |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3706 meaning `to give practical effect to' (@cite{Oxford English |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3707 Dictionary}). Since you evaluate an expression to perform an action, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3708 `execute' has evolved as a synonym to `evaluate'.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3709 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3710 @node Parts of let Expression, Sample let Expression, Prevent confusion, let |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3711 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3712 @subsection The Parts of a @code{let} Expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3713 @cindex @code{let} expression, parts of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3714 @cindex Parts of @code{let} expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3715 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3716 @cindex @samp{varlist} defined |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3717 A @code{let} expression is a list of three parts. The first part is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3718 the symbol @code{let}. The second part is a list, called a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3719 @dfn{varlist}, each element of which is either a symbol by itself or a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3720 two-element list, the first element of which is a symbol. The third |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3721 part of the @code{let} expression is the body of the @code{let}. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3722 body usually consists of one or more lists. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3723 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3724 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3725 A template for a @code{let} expression looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3726 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3727 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3728 (let @var{varlist} @var{body}@dots{}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3729 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3730 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3731 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3732 The symbols in the varlist are the variables that are given initial |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3733 values by the @code{let} special form. Symbols by themselves are given |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3734 the initial value of @code{nil}; and each symbol that is the first |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3735 element of a two-element list is bound to the value that is returned |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3736 when the Lisp interpreter evaluates the second element. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3737 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3738 Thus, a varlist might look like this: @code{(thread (needles 3))}. In |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3739 this case, in a @code{let} expression, Emacs binds the symbol |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3740 @code{thread} to an initial value of @code{nil}, and binds the symbol |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3741 @code{needles} to an initial value of 3. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3742 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3743 When you write a @code{let} expression, what you do is put the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3744 appropriate expressions in the slots of the @code{let} expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3745 template. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3746 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3747 If the varlist is composed of two-element lists, as is often the case, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3748 the template for the @code{let} expression looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3749 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3750 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3751 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3752 (let ((@var{variable} @var{value}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3753 (@var{variable} @var{value}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3754 @dots{}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3755 @var{body}@dots{}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3756 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3757 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3758 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3759 @node Sample let Expression, Uninitialized let Variables, Parts of let Expression, let |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3760 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3761 @subsection Sample @code{let} Expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3762 @cindex Sample @code{let} expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3763 @cindex @code{let} expression sample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3764 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3765 The following expression creates and gives initial values |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3766 to the two variables @code{zebra} and @code{tiger}. The body of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3767 @code{let} expression is a list which calls the @code{message} function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3768 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3769 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3770 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3771 (let ((zebra 'stripes) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3772 (tiger 'fierce)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3773 (message "One kind of animal has %s and another is %s." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3774 zebra tiger)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3775 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3776 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3777 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3778 Here, the varlist is @code{((zebra 'stripes) (tiger 'fierce))}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3779 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3780 The two variables are @code{zebra} and @code{tiger}. Each variable is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3781 the first element of a two-element list and each value is the second |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3782 element of its two-element list. In the varlist, Emacs binds the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3783 variable @code{zebra} to the value @code{stripes}, and binds the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3784 variable @code{tiger} to the value @code{fierce}. In this example, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3785 both values are symbols preceded by a quote. The values could just as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3786 well have been another list or a string. The body of the @code{let} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3787 follows after the list holding the variables. In this example, the body |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3788 is a list that uses the @code{message} function to print a string in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3789 the echo area. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3790 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3791 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3792 You may evaluate the example in the usual fashion, by placing the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3793 cursor after the last parenthesis and typing @kbd{C-x C-e}. When you do |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3794 this, the following will appear in the echo area: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3795 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3796 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3797 "One kind of animal has stripes and another is fierce." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3798 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3799 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3800 As we have seen before, the @code{message} function prints its first |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3801 argument, except for @samp{%s}. In this example, the value of the variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3802 @code{zebra} is printed at the location of the first @samp{%s} and the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3803 value of the variable @code{tiger} is printed at the location of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3804 second @samp{%s}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3805 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3806 @node Uninitialized let Variables, , Sample let Expression, let |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3807 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3808 @subsection Uninitialized Variables in a @code{let} Statement |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3809 @cindex Uninitialized @code{let} variables |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3810 @cindex @code{let} variables uninitialized |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3811 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3812 If you do not bind the variables in a @code{let} statement to specific |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3813 initial values, they will automatically be bound to an initial value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3814 @code{nil}, as in the following expression: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3815 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3816 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3817 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3818 (let ((birch 3) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3819 pine |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3820 fir |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3821 (oak 'some)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3822 (message |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3823 "Here are %d variables with %s, %s, and %s value." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3824 birch pine fir oak)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3825 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3826 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3827 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3828 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3829 Here, the varlist is @code{((birch 3) pine fir (oak 'some))}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3830 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3831 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3832 If you evaluate this expression in the usual way, the following will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3833 appear in your echo area: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3834 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3835 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3836 "Here are 3 variables with nil, nil, and some value." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3837 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3838 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3839 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3840 In this example, Emacs binds the symbol @code{birch} to the number 3, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3841 binds the symbols @code{pine} and @code{fir} to @code{nil}, and binds |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3842 the symbol @code{oak} to the value @code{some}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3843 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3844 Note that in the first part of the @code{let}, the variables @code{pine} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3845 and @code{fir} stand alone as atoms that are not surrounded by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3846 parentheses; this is because they are being bound to @code{nil}, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3847 empty list. But @code{oak} is bound to @code{some} and so is a part of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3848 the list @code{(oak 'some)}. Similarly, @code{birch} is bound to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3849 number 3 and so is in a list with that number. (Since a number |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3850 evaluates to itself, the number does not need to be quoted. Also, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3851 number is printed in the message using a @samp{%d} rather than a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3852 @samp{%s}.) The four variables as a group are put into a list to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3853 delimit them from the body of the @code{let}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3854 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3855 @node if, else, let, Writing Defuns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3856 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3857 @section The @code{if} Special Form |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3858 @findex if |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3859 @cindex Conditional with @code{if} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3860 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3861 A third special form, in addition to @code{defun} and @code{let}, is the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3862 conditional @code{if}. This form is used to instruct the computer to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3863 make decisions. You can write function definitions without using |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3864 @code{if}, but it is used often enough, and is important enough, to be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3865 included here. It is used, for example, in the code for the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3866 function @code{beginning-of-buffer}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3867 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3868 The basic idea behind an @code{if}, is that ``@emph{if} a test is true, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3869 @emph{then} an expression is evaluated.'' If the test is not true, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3870 expression is not evaluated. For example, you might make a decision |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3871 such as, ``if it is warm and sunny, then go to the beach!'' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3872 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3873 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3874 * if in more detail:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3875 * type-of-animal in detail:: An example of an @code{if} expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3876 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3877 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3878 @node if in more detail, type-of-animal in detail, if, if |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3879 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3880 @unnumberedsubsec @code{if} in more detail |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3881 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3882 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3883 @cindex @samp{if-part} defined |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3884 @cindex @samp{then-part} defined |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3885 An @code{if} expression written in Lisp does not use the word `then'; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3886 the test and the action are the second and third elements of the list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3887 whose first element is @code{if}. Nonetheless, the test part of an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3888 @code{if} expression is often called the @dfn{if-part} and the second |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3889 argument is often called the @dfn{then-part}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3890 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3891 Also, when an @code{if} expression is written, the true-or-false-test |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3892 is usually written on the same line as the symbol @code{if}, but the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3893 action to carry out if the test is true, the ``then-part'', is written |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3894 on the second and subsequent lines. This makes the @code{if} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3895 expression easier to read. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3896 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3897 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3898 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3899 (if @var{true-or-false-test} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3900 @var{action-to-carry-out-if-test-is-true}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3901 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3902 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3903 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3904 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3905 The true-or-false-test will be an expression that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3906 is evaluated by the Lisp interpreter. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3907 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3908 Here is an example that you can evaluate in the usual manner. The test |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3909 is whether the number 5 is greater than the number 4. Since it is, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3910 message @samp{5 is greater than 4!} will be printed. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3911 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3912 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3913 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3914 (if (> 5 4) ; @r{if-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3915 (message "5 is greater than 4!")) ; @r{then-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3916 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3917 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3918 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3919 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3920 (The function @code{>} tests whether its first argument is greater than |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3921 its second argument and returns true if it is.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3922 @findex > (greater than) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3923 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3924 Of course, in actual use, the test in an @code{if} expression will not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3925 be fixed for all time as it is by the expression @code{(> 5 4)}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3926 Instead, at least one of the variables used in the test will be bound to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3927 a value that is not known ahead of time. (If the value were known ahead |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3928 of time, we would not need to run the test!) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3929 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3930 For example, the value may be bound to an argument of a function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3931 definition. In the following function definition, the character of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3932 animal is a value that is passed to the function. If the value bound to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3933 @code{characteristic} is @code{fierce}, then the message, @samp{It's a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3934 tiger!} will be printed; otherwise, @code{nil} will be returned. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3935 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3936 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3937 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3938 (defun type-of-animal (characteristic) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3939 "Print message in echo area depending on CHARACTERISTIC. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3940 If the CHARACTERISTIC is the symbol `fierce', |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3941 then warn of a tiger." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3942 (if (equal characteristic 'fierce) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3943 (message "It's a tiger!"))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3944 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3945 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3946 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3947 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3948 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3949 If you are reading this inside of GNU Emacs, you can evaluate the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3950 function definition in the usual way to install it in Emacs, and then you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3951 can evaluate the following two expressions to see the results: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3952 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3953 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3954 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3955 (type-of-animal 'fierce) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3956 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3957 (type-of-animal 'zebra) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3958 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3959 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3960 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3961 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3962 @c Following sentences rewritten to prevent overfull hbox. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3963 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3964 When you evaluate @code{(type-of-animal 'fierce)}, you will see the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3965 following message printed in the echo area: @code{"It's a tiger!"}; and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3966 when you evaluate @code{(type-of-animal 'zebra)} you will see @code{nil} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3967 printed in the echo area. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3968 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3969 @node type-of-animal in detail, , if in more detail, if |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3970 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3971 @subsection The @code{type-of-animal} Function in Detail |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3972 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3973 Let's look at the @code{type-of-animal} function in detail. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3974 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3975 The function definition for @code{type-of-animal} was written by filling |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3976 the slots of two templates, one for a function definition as a whole, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3977 a second for an @code{if} expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3978 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3979 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3980 The template for every function that is not interactive is: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3981 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3982 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3983 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3984 (defun @var{name-of-function} (@var{argument-list}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3985 "@var{documentation}@dots{}" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3986 @var{body}@dots{}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3987 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3988 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3989 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3990 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3991 The parts of the function that match this template look like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3992 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3993 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3994 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3995 (defun type-of-animal (characteristic) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3996 "Print message in echo area depending on CHARACTERISTIC. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3997 If the CHARACTERISTIC is the symbol `fierce', |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3998 then warn of a tiger." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
3999 @var{body: the} @code{if} @var{expression}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4000 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4001 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4002 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4003 The name of function is @code{type-of-animal}; it is passed the value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4004 of one argument. The argument list is followed by a multi-line |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4005 documentation string. The documentation string is included in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4006 example because it is a good habit to write documentation string for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4007 every function definition. The body of the function definition |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4008 consists of the @code{if} expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4009 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4010 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4011 The template for an @code{if} expression looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4012 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4013 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4014 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4015 (if @var{true-or-false-test} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4016 @var{action-to-carry-out-if-the-test-returns-true}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4017 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4018 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4019 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4020 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4021 In the @code{type-of-animal} function, the code for the @code{if} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4022 looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4023 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4024 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4025 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4026 (if (equal characteristic 'fierce) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4027 (message "It's a tiger!"))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4028 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4029 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4030 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4031 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4032 Here, the true-or-false-test is the expression: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4033 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4034 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4035 (equal characteristic 'fierce) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4036 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4037 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4038 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4039 In Lisp, @code{equal} is a function that determines whether its first |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4040 argument is equal to its second argument. The second argument is the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4041 quoted symbol @code{'fierce} and the first argument is the value of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4042 symbol @code{characteristic}---in other words, the argument passed to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4043 this function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4044 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4045 In the first exercise of @code{type-of-animal}, the argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4046 @code{fierce} is passed to @code{type-of-animal}. Since @code{fierce} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4047 is equal to @code{fierce}, the expression, @code{(equal characteristic |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4048 'fierce)}, returns a value of true. When this happens, the @code{if} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4049 evaluates the second argument or then-part of the @code{if}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4050 @code{(message "It's tiger!")}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4051 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4052 On the other hand, in the second exercise of @code{type-of-animal}, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4053 argument @code{zebra} is passed to @code{type-of-animal}. @code{zebra} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4054 is not equal to @code{fierce}, so the then-part is not evaluated and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4055 @code{nil} is returned by the @code{if} expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4056 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4057 @node else, Truth & Falsehood, if, Writing Defuns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4058 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4059 @section If--then--else Expressions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4060 @cindex Else |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4061 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4062 An @code{if} expression may have an optional third argument, called |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4063 the @dfn{else-part}, for the case when the true-or-false-test returns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4064 false. When this happens, the second argument or then-part of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4065 overall @code{if} expression is @emph{not} evaluated, but the third or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4066 else-part @emph{is} evaluated. You might think of this as the cloudy |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4067 day alternative for the decision `if it is warm and sunny, then go to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4068 the beach, else read a book!''. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4069 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4070 The word ``else'' is not written in the Lisp code; the else-part of an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4071 @code{if} expression comes after the then-part. In the written Lisp, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4072 else-part is usually written to start on a line of its own and is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4073 indented less than the then-part: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4074 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4075 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4076 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4077 (if @var{true-or-false-test} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4078 @var{action-to-carry-out-if-the-test-returns-true} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4079 @var{action-to-carry-out-if-the-test-returns-false}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4080 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4081 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4082 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4083 For example, the following @code{if} expression prints the message @samp{4 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4084 is not greater than 5!} when you evaluate it in the usual way: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4085 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4086 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4087 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4088 (if (> 4 5) ; @r{if-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4089 (message "5 is greater than 4!") ; @r{then-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4090 (message "4 is not greater than 5!")) ; @r{else-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4091 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4092 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4093 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4094 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4095 Note that the different levels of indentation make it easy to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4096 distinguish the then-part from the else-part. (GNU Emacs has several |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4097 commands that automatically indent @code{if} expressions correctly. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4098 @xref{Typing Lists, , GNU Emacs Helps You Type Lists}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4099 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4100 We can extend the @code{type-of-animal} function to include an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4101 else-part by simply incorporating an additional part to the @code{if} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4102 expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4103 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4104 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4105 You can see the consequences of doing this if you evaluate the following |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4106 version of the @code{type-of-animal} function definition to install it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4107 and then evaluate the two subsequent expressions to pass different |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4108 arguments to the function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4109 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4110 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4111 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4112 (defun type-of-animal (characteristic) ; @r{Second version.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4113 "Print message in echo area depending on CHARACTERISTIC. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4114 If the CHARACTERISTIC is the symbol `fierce', |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4115 then warn of a tiger; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4116 else say it's not fierce." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4117 (if (equal characteristic 'fierce) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4118 (message "It's a tiger!") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4119 (message "It's not fierce!"))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4120 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4121 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4122 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4123 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4124 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4125 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4126 (type-of-animal 'fierce) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4127 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4128 (type-of-animal 'zebra) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4129 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4130 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4131 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4132 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4133 @c Following sentence rewritten to prevent overfull hbox. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4134 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4135 When you evaluate @code{(type-of-animal 'fierce)}, you will see the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4136 following message printed in the echo area: @code{"It's a tiger!"}; but |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4137 when you evaluate @code{(type-of-animal 'zebra)}, you will see |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4138 @code{"It's not fierce!"}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4139 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4140 (Of course, if the @var{characteristic} were @code{ferocious}, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4141 message @code{"It's not fierce!"} would be printed; and it would be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4142 misleading! When you write code, you need to take into account the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4143 possibility that some such argument will be tested by the @code{if} and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4144 write your program accordingly.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4145 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4146 @node Truth & Falsehood, save-excursion, else, Writing Defuns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4147 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4148 @section Truth and Falsehood in Emacs Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4149 @cindex Truth and falsehood in Emacs Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4150 @cindex Falsehood and truth in Emacs Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4151 @findex nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4152 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4153 There is an important aspect to the truth test in an @code{if} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4154 expression. So far, we have spoken of `true' and `false' as values of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4155 predicates as if they were new kinds of Emacs Lisp objects. In fact, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4156 `false' is just our old friend @code{nil}. Anything else---anything |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4157 at all---is `true'. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4158 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4159 The expression that tests for truth is interpreted as @dfn{true} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4160 if the result of evaluating it is a value that is not @code{nil}. In |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4161 other words, the result of the test is considered true if the value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4162 returned is a number such as 47, a string such as @code{"hello"}, or a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4163 symbol (other than @code{nil}) such as @code{flowers}, or a list, or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4164 even a buffer! |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4165 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4166 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4167 * nil explained:: @code{nil} has two meanings. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4168 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4169 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4170 @node nil explained, , Truth & Falsehood, Truth & Falsehood |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4171 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4172 @unnumberedsubsec An explanation of @code{nil} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4173 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4174 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4175 Before illustrating a test for truth, we need an explanation of @code{nil}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4176 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4177 In Emacs Lisp, the symbol @code{nil} has two meanings. First, it means the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4178 empty list. Second, it means false and is the value returned when a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4179 true-or-false-test tests false. @code{nil} can be written as an empty |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4180 list, @code{()}, or as @code{nil}. As far as the Lisp interpreter is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4181 concerned, @code{()} and @code{nil} are the same. Humans, however, tend |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4182 to use @code{nil} for false and @code{()} for the empty list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4183 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4184 In Emacs Lisp, any value that is not @code{nil}---is not the empty |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4185 list---is considered true. This means that if an evaluation returns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4186 something that is not an empty list, an @code{if} expression will test |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4187 true. For example, if a number is put in the slot for the test, it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4188 will be evaluated and will return itself, since that is what numbers |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4189 do when evaluated. In this conditional, the @code{if} expression will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4190 test true. The expression tests false only when @code{nil}, an empty |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4191 list, is returned by evaluating the expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4192 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4193 You can see this by evaluating the two expressions in the following examples. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4194 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4195 In the first example, the number 4 is evaluated as the test in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4196 @code{if} expression and returns itself; consequently, the then-part |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4197 of the expression is evaluated and returned: @samp{true} appears in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4198 the echo area. In the second example, the @code{nil} indicates false; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4199 consequently, the else-part of the expression is evaluated and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4200 returned: @samp{false} appears in the echo area. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4201 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4202 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4203 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4204 (if 4 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4205 'true |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4206 'false) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4207 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4208 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4209 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4210 (if nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4211 'true |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4212 'false) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4213 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4214 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4215 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4216 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4217 Incidentally, if some other useful value is not available for a test that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4218 returns true, then the Lisp interpreter will return the symbol @code{t} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4219 for true. For example, the expression @code{(> 5 4)} returns @code{t} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4220 when evaluated, as you can see by evaluating it in the usual way: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4221 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4222 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4223 (> 5 4) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4224 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4225 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4226 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4227 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4228 On the other hand, this function returns @code{nil} if the test is false. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4229 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4230 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4231 (> 4 5) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4232 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4233 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4234 @node save-excursion, Review, Truth & Falsehood, Writing Defuns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4235 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4236 @section @code{save-excursion} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4237 @findex save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4238 @cindex Region, what it is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4239 @cindex Preserving point, mark, and buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4240 @cindex Point, mark, buffer preservation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4241 @findex point |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4242 @findex mark |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4243 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4244 The @code{save-excursion} function is the fourth and final special form |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4245 that we will discuss in this chapter. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4246 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4247 In Emacs Lisp programs used for editing, the @code{save-excursion} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4248 function is very common. It saves the location of point and mark, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4249 executes the body of the function, and then restores point and mark to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4250 their previous positions if their locations were changed. Its primary |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4251 purpose is to keep the user from being surprised and disturbed by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4252 unexpected movement of point or mark. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4253 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4254 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4255 * Point and mark:: A review of various locations. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4256 * Template for save-excursion:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4257 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4258 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4259 @node Point and mark, Template for save-excursion, save-excursion, save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4260 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4261 @unnumberedsubsec Point and Mark |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4262 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4263 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4264 Before discussing @code{save-excursion}, however, it may be useful |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4265 first to review what point and mark are in GNU Emacs. @dfn{Point} is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4266 the current location of the cursor. Wherever the cursor |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4267 is, that is point. More precisely, on terminals where the cursor |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4268 appears to be on top of a character, point is immediately before the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4269 character. In Emacs Lisp, point is an integer. The first character in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4270 a buffer is number one, the second is number two, and so on. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4271 function @code{point} returns the current position of the cursor as a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4272 number. Each buffer has its own value for point. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4273 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4274 The @dfn{mark} is another position in the buffer; its value can be set |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4275 with a command such as @kbd{C-@key{SPC}} (@code{set-mark-command}). If |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4276 a mark has been set, you can use the command @kbd{C-x C-x} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4277 (@code{exchange-point-and-mark}) to cause the cursor to jump to the mark |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4278 and set the mark to be the previous position of point. In addition, if |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4279 you set another mark, the position of the previous mark is saved in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4280 mark ring. Many mark positions can be saved this way. You can jump the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4281 cursor to a saved mark by typing @kbd{C-u C-@key{SPC}} one or more |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4282 times. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4283 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4284 The part of the buffer between point and mark is called @dfn{the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4285 region}. Numerous commands work on the region, including |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4286 @code{center-region}, @code{count-lines-region}, @code{kill-region}, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4287 @code{print-region}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4288 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4289 The @code{save-excursion} special form saves the locations of point and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4290 mark and restores those positions after the code within the body of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4291 special form is evaluated by the Lisp interpreter. Thus, if point were |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4292 in the beginning of a piece of text and some code moved point to the end |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4293 of the buffer, the @code{save-excursion} would put point back to where |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4294 it was before, after the expressions in the body of the function were |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4295 evaluated. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4296 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4297 In Emacs, a function frequently moves point as part of its internal |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4298 workings even though a user would not expect this. For example, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4299 @code{count-lines-region} moves point. To prevent the user from being |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4300 bothered by jumps that are both unexpected and (from the user's point of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4301 view) unnecessary, @code{save-excursion} is often used to keep point and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4302 mark in the location expected by the user. The use of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4303 @code{save-excursion} is good housekeeping. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4304 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4305 To make sure the house stays clean, @code{save-excursion} restores the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4306 values of point and mark even if something goes wrong in the code inside |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4307 of it (or, to be more precise and to use the proper jargon, ``in case of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4308 abnormal exit''). This feature is very helpful. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4309 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4310 In addition to recording the values of point and mark, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4311 @code{save-excursion} keeps track of the current buffer, and restores |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4312 it, too. This means you can write code that will change the buffer and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4313 have @code{save-excursion} switch you back to the original buffer. This |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4314 is how @code{save-excursion} is used in @code{append-to-buffer}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4315 (@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4316 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4317 @node Template for save-excursion, , Point and mark, save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4318 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4319 @subsection Template for a @code{save-excursion} Expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4320 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4321 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4322 The template for code using @code{save-excursion} is simple: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4323 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4324 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4325 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4326 (save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4327 @var{body}@dots{}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4328 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4329 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4330 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4331 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4332 The body of the function is one or more expressions that will be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4333 evaluated in sequence by the Lisp interpreter. If there is more than |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4334 one expression in the body, the value of the last one will be returned |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4335 as the value of the @code{save-excursion} function. The other |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4336 expressions in the body are evaluated only for their side effects; and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4337 @code{save-excursion} itself is used only for its side effect (which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4338 is restoring the positions of point and mark). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4339 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4340 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4341 In more detail, the template for a @code{save-excursion} expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4342 looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4343 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4344 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4345 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4346 (save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4347 @var{first-expression-in-body} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4348 @var{second-expression-in-body} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4349 @var{third-expression-in-body} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4350 @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4351 @var{last-expression-in-body}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4352 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4353 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4354 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4355 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4356 An expression, of course, may be a symbol on its own or a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4357 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4358 In Emacs Lisp code, a @code{save-excursion} expression often occurs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4359 within the body of a @code{let} expression. It looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4360 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4361 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4362 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4363 (let @var{varlist} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4364 (save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4365 @var{body}@dots{})) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4366 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4367 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4368 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4369 @node Review, defun Exercises, save-excursion, Writing Defuns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4370 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4371 @section Review |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4372 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4373 In the last few chapters we have introduced a fair number of functions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4374 and special forms. Here they are described in brief, along with a few |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4375 similar functions that have not been mentioned yet. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4376 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4377 @table @code |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4378 @item eval-last-sexp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4379 Evaluate the last symbolic expression before the current location of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4380 point. The value is printed in the echo area unless the function is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4381 invoked with an argument; in that case, the output is printed in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4382 current buffer. This command is normally bound to @kbd{C-x C-e}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4383 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4384 @item defun |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4385 Define function. This special form has up to five parts: the name, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4386 a template for the arguments that will be passed to the function, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4387 documentation, an optional interactive declaration, and the body of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4388 definition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4389 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4390 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4391 For example: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4392 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4393 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4394 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4395 (defun back-to-indentation () |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4396 "Move point to first visible character on line." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4397 (interactive) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4398 (beginning-of-line 1) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4399 (skip-chars-forward " \t")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4400 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4401 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4402 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4403 @item interactive |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4404 Declare to the interpreter that the function can be used |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4405 interactively. This special form may be followed by a string with one |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4406 or more parts that pass the information to the arguments of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4407 function, in sequence. These parts may also tell the interpreter to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4408 prompt for information. Parts of the string are separated by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4409 newlines, @samp{\n}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4410 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4411 Common code characters are: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4412 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4413 @table @code |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4414 @item b |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4415 The name of an existing buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4416 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4417 @item f |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4418 The name of an existing file. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4419 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4420 @item p |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4421 The numeric prefix argument. (Note that this `p' is lower case.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4422 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4423 @item r |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4424 Point and the mark, as two numeric arguments, smallest first. This |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4425 is the only code letter that specifies two successive arguments |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4426 rather than one. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4427 @end table |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4428 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4429 @xref{Interactive Codes, , Code Characters for @samp{interactive}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4430 elisp, The GNU Emacs Lisp Reference Manual}, for a complete list of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4431 code characters. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4432 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4433 @item let |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4434 Declare that a list of variables is for use within the body of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4435 @code{let} and give them an initial value, either @code{nil} or a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4436 specified value; then evaluate the rest of the expressions in the body |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4437 of the @code{let} and return the value of the last one. Inside the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4438 body of the @code{let}, the Lisp interpreter does not see the values of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4439 the variables of the same names that are bound outside of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4440 @code{let}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4441 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4442 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4443 For example, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4444 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4445 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4446 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4447 (let ((foo (buffer-name)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4448 (bar (buffer-size))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4449 (message |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4450 "This buffer is %s and has %d characters." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4451 foo bar)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4452 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4453 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4454 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4455 @item save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4456 Record the values of point and mark and the current buffer before |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4457 evaluating the body of this special form. Restore the values of point |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4458 and mark and buffer afterward. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4459 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4460 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4461 For example, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4462 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4463 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4464 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4465 (message "We are %d characters into this buffer." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4466 (- (point) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4467 (save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4468 (goto-char (point-min)) (point)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4469 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4470 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4471 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4472 @item if |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4473 Evaluate the first argument to the function; if it is true, evaluate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4474 the second argument; else evaluate the third argument, if there is one. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4475 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4476 The @code{if} special form is called a @dfn{conditional}. There are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4477 other conditionals in Emacs Lisp, but @code{if} is perhaps the most |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4478 commonly used. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4479 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4480 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4481 For example, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4482 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4483 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4484 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4485 (if (string-equal |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4486 (number-to-string 21) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4487 (substring (emacs-version) 10 12)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4488 (message "This is version 21 Emacs") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4489 (message "This is not version 21 Emacs")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4490 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4491 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4492 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4493 @item equal |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4494 @itemx eq |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4495 Test whether two objects are the same. @code{equal} uses one meaning |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4496 of the word `same' and @code{eq} uses another: @code{equal} returns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4497 true if the two objects have a similar structure and contents, such as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4498 two copies of the same book. On the other hand, @code{eq}, returns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4499 true if both arguments are actually the same object. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4500 @findex equal |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4501 @findex eq |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4502 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4503 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4504 @item < |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4505 @itemx > |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4506 @itemx <= |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4507 @itemx >= |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4508 The @code{<} function tests whether its first argument is smaller than |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4509 its second argument. A corresponding function, @code{>}, tests whether |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4510 the first argument is greater than the second. Likewise, @code{<=} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4511 tests whether the first argument is less than or equal to the second and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4512 @code{>=} tests whether the first argument is greater than or equal to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4513 the second. In all cases, both arguments must be numbers or markers |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4514 (markers indicate positions in buffers). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4515 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4516 @item string< |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4517 @itemx string-lessp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4518 @itemx string= |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4519 @itemx string-equal |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4520 The @code{string-lessp} function tests whether its first argument is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4521 smaller than the second argument. A shorter, alternative name for the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4522 same function (a @code{defalias}) is @code{string<}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4523 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4524 The arguments to @code{string-lessp} must be strings or symbols; the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4525 ordering is lexicographic, so case is significant. The print names of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4526 symbols are used instead of the symbols themselves. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4527 |
42109
24f8e84cb04d
Indexed `empty string' definition.
Robert J. Chassell <bob@rattlesnake.com>
parents:
42108
diff
changeset
|
4528 @cindex @samp{empty string} defined |
42108
dcab51f5352e
Define `empty string' a second time, in a slightly more visible location.
Robert J. Chassell <bob@rattlesnake.com>
parents:
41872
diff
changeset
|
4529 An empty string, @samp{""}, a string with no characters in it, is |
dcab51f5352e
Define `empty string' a second time, in a slightly more visible location.
Robert J. Chassell <bob@rattlesnake.com>
parents:
41872
diff
changeset
|
4530 smaller than any string of characters. |
dcab51f5352e
Define `empty string' a second time, in a slightly more visible location.
Robert J. Chassell <bob@rattlesnake.com>
parents:
41872
diff
changeset
|
4531 |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4532 @code{string-equal} provides the corresponding test for equality. Its |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4533 shorter, alternative name is @code{string=}. There are no string test |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4534 functions that correspond to @var{>}, @code{>=}, or @code{<=}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4535 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4536 @item message |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4537 Print a message in the echo area. The first argument is a string that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4538 can contain @samp{%s}, @samp{%d}, or @samp{%c} to print the value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4539 arguments that follow the string. The argument used by @samp{%s} must |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4540 be a string or a symbol; the argument used by @samp{%d} must be a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4541 number. The argument used by @samp{%c} must be an ascii code number; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4542 it will be printed as the character with that @sc{ascii} code. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4543 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4544 @item setq |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4545 @itemx set |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4546 The @code{setq} function sets the value of its first argument to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4547 value of the second argument. The first argument is automatically |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4548 quoted by @code{setq}. It does the same for succeeding pairs of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4549 arguments. Another function, @code{set}, takes only two arguments and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4550 evaluates both of them before setting the value returned by its first |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4551 argument to the value returned by its second argument. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4552 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4553 @item buffer-name |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4554 Without an argument, return the name of the buffer, as a string. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4555 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4556 @itemx buffer-file-name |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4557 Without an argument, return the name of the file the buffer is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4558 visiting. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4559 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4560 @item current-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4561 Return the buffer in which Emacs is active; it may not be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4562 the buffer that is visible on the screen. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4563 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4564 @item other-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4565 Return the most recently selected buffer (other than the buffer passed |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4566 to @code{other-buffer} as an argument and other than the current |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4567 buffer). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4568 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4569 @item switch-to-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4570 Select a buffer for Emacs to be active in and display it in the current |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4571 window so users can look at it. Usually bound to @kbd{C-x b}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4572 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4573 @item set-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4574 Switch Emacs' attention to a buffer on which programs will run. Don't |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4575 alter what the window is showing. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4576 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4577 @item buffer-size |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4578 Return the number of characters in the current buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4579 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4580 @item point |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4581 Return the value of the current position of the cursor, as an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4582 integer counting the number of characters from the beginning of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4583 buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4584 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4585 @item point-min |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4586 Return the minimum permissible value of point in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4587 the current buffer. This is 1, unless narrowing is in effect. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4588 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4589 @item point-max |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4590 Return the value of the maximum permissible value of point in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4591 current buffer. This is the end of the buffer, unless narrowing is in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4592 effect. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4593 @end table |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4594 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4595 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4596 @node defun Exercises, , Review, Writing Defuns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4597 @section Exercises |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4598 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4599 @itemize @bullet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4600 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4601 Write a non-interactive function that doubles the value of its |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4602 argument, a number. Make that function interactive. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4603 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4604 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4605 Write a function that tests whether the current value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4606 @code{fill-column} is greater than the argument passed to the function, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4607 and if so, prints an appropriate message. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4608 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4609 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4610 @node Buffer Walk Through, More Complex, Writing Defuns, Top |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4611 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4612 @chapter A Few Buffer--Related Functions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4613 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4614 In this chapter we study in detail several of the functions used in GNU |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4615 Emacs. This is called a ``walk-through''. These functions are used as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4616 examples of Lisp code, but are not imaginary examples; with the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4617 exception of the first, simplified function definition, these functions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4618 show the actual code used in GNU Emacs. You can learn a great deal from |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4619 these definitions. The functions described here are all related to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4620 buffers. Later, we will study other functions. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4621 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4622 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4623 * Finding More:: How to find more information. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4624 * simplified-beginning-of-buffer:: Shows @code{goto-char}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4625 @code{point-min}, and @code{push-mark}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4626 * mark-whole-buffer:: Almost the same as @code{beginning-of-buffer}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4627 * append-to-buffer:: Uses @code{save-excursion} and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4628 @code{insert-buffer-substring}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4629 * Buffer Related Review:: Review. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4630 * Buffer Exercises:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4631 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4632 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4633 @node Finding More, simplified-beginning-of-buffer, Buffer Walk Through, Buffer Walk Through |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4634 @section Finding More Information |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4635 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4636 @findex describe-function, @r{introduced} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4637 @cindex Find function documentation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4638 In this walk-through, I will describe each new function as we come to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4639 it, sometimes in detail and sometimes briefly. If you are interested, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4640 you can get the full documentation of any Emacs Lisp function at any |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4641 time by typing @kbd{C-h f} and then the name of the function (and then |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4642 @key{RET}). Similarly, you can get the full documentation for a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4643 variable by typing @kbd{C-h v} and then the name of the variable (and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4644 then @key{RET}). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4645 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4646 @cindex Find source of function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4647 In versions 20 and higher, when a function is written in Emacs Lisp, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4648 @code{describe-function} will also tell you the location of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4649 function definition. If you move point over the file name and press |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4650 the @key{RET} key, which is this case means @code{help-follow} rather |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4651 than `return' or `enter', Emacs will take you directly to the function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4652 definition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4653 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4654 More generally, if you want to see a function in its original source |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4655 file, you can use the @code{find-tags} function to jump to it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4656 @code{find-tags} works with a wide variety of languages, not just |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4657 Lisp, and C, and it works with non-programming text as well. For |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4658 example, @code{find-tags} will jump to the various nodes in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4659 Texinfo source file of this document. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4660 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4661 The @code{find-tags} function depends on `tags tables' that record |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4662 the locations of the functions, variables, and other items to which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4663 @code{find-tags} jumps. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4664 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4665 To use the @code{find-tags} command, type @kbd{M-.} (i.e., type the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4666 @key{META} key and the period key at the same time, or else type the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4667 @key{ESC} key and then type the period key), and then, at the prompt, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4668 type in the name of the function whose source code you want to see, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4669 such as @code{mark-whole-buffer}, and then type @key{RET}. Emacs will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4670 switch buffers and display the source code for the function on your |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4671 screen. To switch back to your current buffer, type @kbd{C-x b |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4672 @key{RET}}. (On some keyboards, the @key{META} key is labelled |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4673 @key{ALT}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4674 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4675 @c !!! 21.0.100 tags table location in this paragraph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4676 @cindex TAGS table, specifying |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4677 @findex find-tags |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4678 Depending on how the initial default values of your copy of Emacs are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4679 set, you may also need to specify the location of your `tags table', |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4680 which is a file called @file{TAGS}. For example, if you are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4681 interested in Emacs sources, the tags table you will most likely want, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4682 if it has already been created for you, will be in a subdirectory of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4683 the @file{/usr/local/share/emacs/} directory; thus you would use the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4684 @code{M-x visit-tags-table} command and specify a pathname such as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4685 @file{/usr/local/share/emacs/21.0.100/lisp/TAGS} or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4686 @file{/usr/local/src/emacs/lisp/TAGS}. If the tags table has |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4687 not already been created, you will have to create it yourself. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4688 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4689 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4690 To create a @file{TAGS} file in a specific directory, switch to that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4691 directory in Emacs using @kbd{M-x cd} command, or list the directory |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4692 with @kbd{C-x d} (@code{dired}). Then run the compile command, with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4693 @w{@code{etags *.el}} as the command to execute |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4694 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4695 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4696 M-x compile RET etags *.el RET |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4697 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4698 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4699 For more information, see @ref{etags, , Create Your Own @file{TAGS} File}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4700 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4701 After you become more familiar with Emacs Lisp, you will find that you will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4702 frequently use @code{find-tags} to navigate your way around source code; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4703 and you will create your own @file{TAGS} tables. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4704 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4705 @cindex Library, as term for `file' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4706 Incidentally, the files that contain Lisp code are conventionally |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4707 called @dfn{libraries}. The metaphor is derived from that of a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4708 specialized library, such as a law library or an engineering library, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4709 rather than a general library. Each library, or file, contains |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4710 functions that relate to a particular topic or activity, such as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4711 @file{abbrev.el} for handling abbreviations and other typing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4712 shortcuts, and @file{help.el} for on-line help. (Sometimes several |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4713 libraries provide code for a single activity, as the various |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4714 @file{rmail@dots{}} files provide code for reading electronic mail.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4715 In @cite{The GNU Emacs Manual}, you will see sentences such as ``The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4716 @kbd{C-h p} command lets you search the standard Emacs Lisp libraries |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4717 by topic keywords.'' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4718 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4719 @node simplified-beginning-of-buffer, mark-whole-buffer, Finding More, Buffer Walk Through |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4720 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4721 @section A Simplified @code{beginning-of-buffer} Definition |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4722 @findex simplified-beginning-of-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4723 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4724 The @code{beginning-of-buffer} command is a good function to start with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4725 since you are likely to be familiar with it and it is easy to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4726 understand. Used as an interactive command, @code{beginning-of-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4727 moves the cursor to the beginning of the buffer, leaving the mark at the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4728 previous position. It is generally bound to @kbd{M-<}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4729 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4730 In this section, we will discuss a shortened version of the function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4731 that shows how it is most frequently used. This shortened function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4732 works as written, but it does not contain the code for a complex option. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4733 In another section, we will describe the entire function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4734 (@xref{beginning-of-buffer, , Complete Definition of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4735 @code{beginning-of-buffer}}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4736 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4737 Before looking at the code, let's consider what the function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4738 definition has to contain: it must include an expression that makes |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4739 the function interactive so it can be called by typing @kbd{M-x |
44899
ebddb2618c17
Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents:
43431
diff
changeset
|
4740 beginning-of-buffer} or by typing a keychord such as @kbd{M-<}; it |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4741 must include code to leave a mark at the original position in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4742 buffer; and it must include code to move the cursor to the beginning |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4743 of the buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4744 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4745 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4746 Here is the complete text of the shortened version of the function: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4747 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4748 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4749 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4750 (defun simplified-beginning-of-buffer () |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4751 "Move point to the beginning of the buffer; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4752 leave mark at previous position." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4753 (interactive) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4754 (push-mark) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4755 (goto-char (point-min))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4756 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4757 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4758 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4759 Like all function definitions, this definition has five parts following |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4760 the special form @code{defun}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4761 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4762 @enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4763 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4764 The name: in this example, @code{simplified-beginning-of-buffer}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4765 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4766 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4767 A list of the arguments: in this example, an empty list, @code{()}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4768 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4769 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4770 The documentation string. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4771 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4772 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4773 The interactive expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4774 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4775 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4776 The body. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4777 @end enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4778 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4779 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4780 In this function definition, the argument list is empty; this means that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4781 this function does not require any arguments. (When we look at the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4782 definition for the complete function, we will see that it may be passed |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4783 an optional argument.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4784 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4785 The interactive expression tells Emacs that the function is intended to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4786 be used interactively. In this example, @code{interactive} does not have |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4787 an argument because @code{simplified-beginning-of-buffer} does not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4788 require one. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4789 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4790 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4791 The body of the function consists of the two lines: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4792 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4793 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4794 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4795 (push-mark) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4796 (goto-char (point-min)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4797 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4798 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4799 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4800 The first of these lines is the expression, @code{(push-mark)}. When |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4801 this expression is evaluated by the Lisp interpreter, it sets a mark at |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4802 the current position of the cursor, wherever that may be. The position |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4803 of this mark is saved in the mark ring. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4804 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4805 The next line is @code{(goto-char (point-min))}. This expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4806 jumps the cursor to the minimum point in the buffer, that is, to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4807 beginning of the buffer (or to the beginning of the accessible portion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4808 of the buffer if it is narrowed. @xref{Narrowing & Widening, , |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4809 Narrowing and Widening}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4810 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4811 The @code{push-mark} command sets a mark at the place where the cursor |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4812 was located before it was moved to the beginning of the buffer by the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4813 @code{(goto-char (point-min))} expression. Consequently, you can, if |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4814 you wish, go back to where you were originally by typing @kbd{C-x C-x}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4815 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4816 That is all there is to the function definition! |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4817 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4818 @findex describe-function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4819 When you are reading code such as this and come upon an unfamiliar |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4820 function, such as @code{goto-char}, you can find out what it does by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4821 using the @code{describe-function} command. To use this command, type |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4822 @kbd{C-h f} and then type in the name of the function and press |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4823 @key{RET}. The @code{describe-function} command will print the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4824 function's documentation string in a @file{*Help*} window. For |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4825 example, the documentation for @code{goto-char} is: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4826 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4827 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4828 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4829 One arg, a number. Set point to that number. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4830 Beginning of buffer is position (point-min), |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4831 end is (point-max). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4832 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4833 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4834 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4835 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4836 (The prompt for @code{describe-function} will offer you the symbol |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4837 under or preceding the cursor, so you can save typing by positioning |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4838 the cursor right over or after the function and then typing @kbd{C-h f |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4839 @key{RET}}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4840 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4841 The @code{end-of-buffer} function definition is written in the same way as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4842 the @code{beginning-of-buffer} definition except that the body of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4843 function contains the expression @code{(goto-char (point-max))} in place |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4844 of @code{(goto-char (point-min))}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4845 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4846 @node mark-whole-buffer, append-to-buffer, simplified-beginning-of-buffer, Buffer Walk Through |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4847 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4848 @section The Definition of @code{mark-whole-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4849 @findex mark-whole-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4850 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4851 The @code{mark-whole-buffer} function is no harder to understand than the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4852 @code{simplified-beginning-of-buffer} function. In this case, however, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4853 we will look at the complete function, not a shortened version. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4854 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4855 The @code{mark-whole-buffer} function is not as commonly used as the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4856 @code{beginning-of-buffer} function, but is useful nonetheless: it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4857 marks a whole buffer as a region by putting point at the beginning and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4858 a mark at the end of the buffer. It is generally bound to @kbd{C-x |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4859 h}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4860 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4861 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4862 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4863 * mark-whole-buffer overview:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4864 * Body of mark-whole-buffer:: Only three lines of code. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4865 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4866 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4867 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4868 @node mark-whole-buffer overview, Body of mark-whole-buffer, mark-whole-buffer, mark-whole-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4869 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4870 @unnumberedsubsec An overview of @code{mark-whole-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4871 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4872 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4873 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4874 In GNU Emacs 20, the code for the complete function looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4875 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4876 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4877 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4878 (defun mark-whole-buffer () |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4879 "Put point at beginning and mark at end of buffer." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4880 (interactive) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4881 (push-mark (point)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4882 (push-mark (point-max)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4883 (goto-char (point-min))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4884 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4885 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4886 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4887 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4888 Like all other functions, the @code{mark-whole-buffer} function fits |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4889 into the template for a function definition. The template looks like |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4890 this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4891 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4892 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4893 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4894 (defun @var{name-of-function} (@var{argument-list}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4895 "@var{documentation}@dots{}" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4896 (@var{interactive-expression}@dots{}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4897 @var{body}@dots{}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4898 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4899 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4900 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4901 Here is how the function works: the name of the function is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4902 @code{mark-whole-buffer}; it is followed by an empty argument list, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4903 @samp{()}, which means that the function does not require arguments. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4904 The documentation comes next. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4905 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4906 The next line is an @code{(interactive)} expression that tells Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4907 that the function will be used interactively. These details are similar |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4908 to the @code{simplified-beginning-of-buffer} function described in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4909 previous section. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4910 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4911 @node Body of mark-whole-buffer, , mark-whole-buffer overview, mark-whole-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4912 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4913 @subsection Body of @code{mark-whole-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4914 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4915 The body of the @code{mark-whole-buffer} function consists of three |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4916 lines of code: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4917 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4918 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4919 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4920 (push-mark (point)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4921 (push-mark (point-max)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4922 (goto-char (point-min)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4923 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4924 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4925 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4926 The first of these lines is the expression, @code{(push-mark (point))}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4927 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4928 This line does exactly the same job as the first line of the body of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4929 the @code{simplified-beginning-of-buffer} function, which is written |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4930 @code{(push-mark)}. In both cases, the Lisp interpreter sets a mark |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4931 at the current position of the cursor. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4932 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4933 I don't know why the expression in @code{mark-whole-buffer} is written |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4934 @code{(push-mark (point))} and the expression in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4935 @code{beginning-of-buffer} is written @code{(push-mark)}. Perhaps |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4936 whoever wrote the code did not know that the arguments for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4937 @code{push-mark} are optional and that if @code{push-mark} is not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4938 passed an argument, the function automatically sets mark at the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4939 location of point by default. Or perhaps the expression was written |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4940 so as to parallel the structure of the next line. In any case, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4941 line causes Emacs to determine the position of point and set a mark |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4942 there. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4943 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4944 The next line of @code{mark-whole-buffer} is @code{(push-mark (point-max)}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4945 This expression sets a mark at the point in the buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4946 that has the highest number. This will be the end of the buffer (or, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4947 if the buffer is narrowed, the end of the accessible portion of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4948 buffer. @xref{Narrowing & Widening, , Narrowing and Widening}, for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4949 more about narrowing.) After this mark has been set, the previous |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4950 mark, the one set at point, is no longer set, but Emacs remembers its |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4951 position, just as all other recent marks are always remembered. This |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4952 means that you can, if you wish, go back to that position by typing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4953 @kbd{C-u C-@key{SPC}} twice. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4954 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4955 (In GNU Emacs 21, the @code{(push-mark (point-max)} is slightly more |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4956 complicated than shown here. The line reads |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4957 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4958 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4959 (push-mark (point-max) nil t) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4960 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4961 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4962 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4963 (The expression works nearly the same as before. It sets a mark at |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4964 the highest numbered place in the buffer that it can. However, in |
41872
2a4f1d831675
Fixed typographic error.
Robert J. Chassell <bob@rattlesnake.com>
parents:
41674
diff
changeset
|
4965 this version, @code{push-mark} has two additional arguments. The |
2a4f1d831675
Fixed typographic error.
Robert J. Chassell <bob@rattlesnake.com>
parents:
41674
diff
changeset
|
4966 second argument to @code{push-mark} is @code{nil}. This tells the |
2a4f1d831675
Fixed typographic error.
Robert J. Chassell <bob@rattlesnake.com>
parents:
41674
diff
changeset
|
4967 function it @emph{should} display a message that says `Mark set' when |
2a4f1d831675
Fixed typographic error.
Robert J. Chassell <bob@rattlesnake.com>
parents:
41674
diff
changeset
|
4968 it pushes the mark. The third argument is @code{t}. This tells |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4969 @code{push-mark} to activate the mark when Transient Mark mode is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4970 turned on. Transient Mark mode highlights the currently active |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4971 region. It is usually turned off.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4972 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4973 Finally, the last line of the function is @code{(goto-char |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4974 (point-min)))}. This is written exactly the same way as it is written |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4975 in @code{beginning-of-buffer}. The expression moves the cursor to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4976 the minimum point in the buffer, that is, to the beginning of the buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4977 (or to the beginning of the accessible portion of the buffer). As a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4978 result of this, point is placed at the beginning of the buffer and mark |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4979 is set at the end of the buffer. The whole buffer is, therefore, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4980 region. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4981 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4982 @node append-to-buffer, Buffer Related Review, mark-whole-buffer, Buffer Walk Through |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4983 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4984 @section The Definition of @code{append-to-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4985 @findex append-to-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4986 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4987 The @code{append-to-buffer} command is very nearly as simple as the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4988 @code{mark-whole-buffer} command. What it does is copy the region (that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4989 is, the part of the buffer between point and mark) from the current |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4990 buffer to a specified buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4991 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4992 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4993 * append-to-buffer overview:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4994 * append interactive:: A two part interactive expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4995 * append-to-buffer body:: Incorporates a @code{let} expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4996 * append save-excursion:: How the @code{save-excursion} works. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4997 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4998 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
4999 @node append-to-buffer overview, append interactive, append-to-buffer, append-to-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5000 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5001 @unnumberedsubsec An Overview of @code{append-to-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5002 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5003 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5004 @findex insert-buffer-substring |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5005 The @code{append-to-buffer} command uses the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5006 @code{insert-buffer-substring} function to copy the region. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5007 @code{insert-buffer-substring} is described by its name: it takes a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5008 string of characters from part of a buffer, a ``substring'', and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5009 inserts them into another buffer. Most of @code{append-to-buffer} is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5010 concerned with setting up the conditions for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5011 @code{insert-buffer-substring} to work: the code must specify both the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5012 buffer to which the text will go and the region that will be copied. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5013 Here is the complete text of the function: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5014 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5015 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5016 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5017 (defun append-to-buffer (buffer start end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5018 "Append to specified buffer the text of the region. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5019 It is inserted into that buffer before its point. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5020 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5021 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5022 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5023 When calling from a program, give three arguments: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5024 a buffer or the name of one, and two character numbers |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5025 specifying the portion of the current buffer to be copied." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5026 (interactive "BAppend to buffer:@: \nr") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5027 (let ((oldbuf (current-buffer))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5028 (save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5029 (set-buffer (get-buffer-create buffer)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5030 (insert-buffer-substring oldbuf start end)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5031 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5032 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5033 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5034 The function can be understood by looking at it as a series of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5035 filled-in templates. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5036 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5037 The outermost template is for the function definition. In this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5038 function, it looks like this (with several slots filled in): |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5039 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5040 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5041 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5042 (defun append-to-buffer (buffer start end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5043 "@var{documentation}@dots{}" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5044 (interactive "BAppend to buffer:@: \nr") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5045 @var{body}@dots{}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5046 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5047 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5048 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5049 The first line of the function includes its name and three arguments. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5050 The arguments are the @code{buffer} to which the text will be copied, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5051 the @code{start} and @code{end} of the region in the current buffer that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5052 will be copied. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5053 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5054 The next part of the function is the documentation, which is clear and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5055 complete. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5056 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5057 @node append interactive, append-to-buffer body, append-to-buffer overview, append-to-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5058 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5059 @subsection The @code{append-to-buffer} Interactive Expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5060 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5061 Since the @code{append-to-buffer} function will be used interactively, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5062 the function must have an @code{interactive} expression. (For a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5063 review of @code{interactive}, see @ref{Interactive, , Making a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5064 Function Interactive}.) The expression reads as follows: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5065 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5066 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5067 (interactive "BAppend to buffer:@: \nr") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5068 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5069 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5070 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5071 This expression has an argument inside of quotation marks and that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5072 argument has two parts, separated by @samp{\n}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5073 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5074 The first part is @samp{BAppend to buffer:@: }. Here, the @samp{B} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5075 tells Emacs to ask for the name of the buffer that will be passed to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5076 function. Emacs will ask for the name by prompting the user in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5077 minibuffer, using the string following the @samp{B}, which is the string |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5078 @samp{Append to buffer:@: }. Emacs then binds the variable @code{buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5079 in the function's argument list to the specified buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5080 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5081 The newline, @samp{\n}, separates the first part of the argument from |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5082 the second part. It is followed by an @samp{r} that tells Emacs to bind |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5083 the two arguments that follow the symbol @code{buffer} in the function's |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5084 argument list (that is, @code{start} and @code{end}) to the values of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5085 point and mark. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5086 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5087 @node append-to-buffer body, append save-excursion, append interactive, append-to-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5088 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5089 @subsection The Body of @code{append-to-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5090 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5091 The body of the @code{append-to-buffer} function begins with @code{let}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5092 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5093 As we have seen before (@pxref{let, , @code{let}}), the purpose of a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5094 @code{let} expression is to create and give initial values to one or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5095 more variables that will only be used within the body of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5096 @code{let}. This means that such a variable will not be confused with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5097 any variable of the same name outside the @code{let} expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5098 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5099 We can see how the @code{let} expression fits into the function as a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5100 whole by showing a template for @code{append-to-buffer} with the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5101 @code{let} expression in outline: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5102 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5103 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5104 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5105 (defun append-to-buffer (buffer start end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5106 "@var{documentation}@dots{}" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5107 (interactive "BAppend to buffer:@: \nr") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5108 (let ((@var{variable} @var{value})) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5109 @var{body}@dots{}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5110 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5111 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5112 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5113 The @code{let} expression has three elements: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5114 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5115 @enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5116 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5117 The symbol @code{let}; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5118 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5119 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5120 A varlist containing, in this case, a single two-element list, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5121 @code{(@var{variable} @var{value})}; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5122 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5123 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5124 The body of the @code{let} expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5125 @end enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5126 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5127 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5128 In the @code{append-to-buffer} function, the varlist looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5129 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5130 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5131 (oldbuf (current-buffer)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5132 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5133 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5134 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5135 In this part of the @code{let} expression, the one variable, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5136 @code{oldbuf}, is bound to the value returned by the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5137 @code{(current-buffer)} expression. The variable, @code{oldbuf}, is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5138 used to keep track of the buffer in which you are working and from |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5139 which you will copy. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5140 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5141 The element or elements of a varlist are surrounded by a set of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5142 parentheses so the Lisp interpreter can distinguish the varlist from |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5143 the body of the @code{let}. As a consequence, the two-element list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5144 within the varlist is surrounded by a circumscribing set of parentheses. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5145 The line looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5146 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5147 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5148 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5149 (let ((oldbuf (current-buffer))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5150 @dots{} ) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5151 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5152 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5153 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5154 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5155 The two parentheses before @code{oldbuf} might surprise you if you did |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5156 not realize that the first parenthesis before @code{oldbuf} marks the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5157 boundary of the varlist and the second parenthesis marks the beginning |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5158 of the two-element list, @code{(oldbuf (current-buffer))}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5159 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5160 @node append save-excursion, , append-to-buffer body, append-to-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5161 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5162 @subsection @code{save-excursion} in @code{append-to-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5163 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5164 The body of the @code{let} expression in @code{append-to-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5165 consists of a @code{save-excursion} expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5166 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5167 The @code{save-excursion} function saves the locations of point and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5168 mark, and restores them to those positions after the expressions in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5169 body of the @code{save-excursion} complete execution. In addition, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5170 @code{save-excursion} keeps track of the original buffer, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5171 restores it. This is how @code{save-excursion} is used in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5172 @code{append-to-buffer}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5173 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5174 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5175 @cindex Indentation for formatting |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5176 @cindex Formatting convention |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5177 Incidentally, it is worth noting here that a Lisp function is normally |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5178 formatted so that everything that is enclosed in a multi-line spread is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5179 indented more to the right than the first symbol. In this function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5180 definition, the @code{let} is indented more than the @code{defun}, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5181 the @code{save-excursion} is indented more than the @code{let}, like |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5182 this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5183 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5184 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5185 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5186 (defun @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5187 @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5188 @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5189 (let@dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5190 (save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5191 @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5192 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5193 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5194 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5195 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5196 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5197 This formatting convention makes it easy to see that the two lines in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5198 the body of the @code{save-excursion} are enclosed by the parentheses |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5199 associated with @code{save-excursion}, just as the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5200 @code{save-excursion} itself is enclosed by the parentheses associated |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5201 with the @code{let}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5202 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5203 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5204 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5205 (let ((oldbuf (current-buffer))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5206 (save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5207 (set-buffer (get-buffer-create buffer)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5208 (insert-buffer-substring oldbuf start end)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5209 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5210 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5211 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5212 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5213 The use of the @code{save-excursion} function can be viewed as a process |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5214 of filling in the slots of a template: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5215 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5216 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5217 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5218 (save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5219 @var{first-expression-in-body} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5220 @var{second-expression-in-body} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5221 @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5222 @var{last-expression-in-body}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5223 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5224 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5225 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5226 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5227 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5228 In this function, the body of the @code{save-excursion} contains only |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5229 two expressions. The body looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5230 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5231 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5232 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5233 (set-buffer (get-buffer-create buffer)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5234 (insert-buffer-substring oldbuf start end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5235 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5236 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5237 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5238 When the @code{append-to-buffer} function is evaluated, the two |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5239 expressions in the body of the @code{save-excursion} are evaluated in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5240 sequence. The value of the last expression is returned as the value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5241 the @code{save-excursion} function; the other expression is evaluated |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5242 only for its side effects. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5243 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5244 The first line in the body of the @code{save-excursion} uses the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5245 @code{set-buffer} function to change the current buffer to the one |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5246 specified in the first argument to @code{append-to-buffer}. (Changing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5247 the buffer is the side effect; as we have said before, in Lisp, a side |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5248 effect is often the primary thing we want.) The second line does the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5249 primary work of the function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5251 The @code{set-buffer} function changes Emacs' attention to the buffer to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5252 which the text will be copied and from which @code{save-excursion} will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5253 return. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5254 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5255 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5256 The line looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5257 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5258 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5259 (set-buffer (get-buffer-create buffer)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5260 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5261 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5262 The innermost expression of this list is @code{(get-buffer-create |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5263 buffer)}. This expression uses the @code{get-buffer-create} function, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5264 which either gets the named buffer, or if it does not exist, creates one |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5265 with the given name. This means you can use @code{append-to-buffer} to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5266 put text into a buffer that did not previously exist. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5267 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5268 @code{get-buffer-create} also keeps @code{set-buffer} from getting an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5269 unnecessary error: @code{set-buffer} needs a buffer to go to; if you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5270 were to specify a buffer that does not exist, Emacs would baulk. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5271 Since @code{get-buffer-create} will create a buffer if none exists, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5272 @code{set-buffer} is always provided with a buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5273 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5274 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5275 The last line of @code{append-to-buffer} does the work of appending |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5276 the text: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5277 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5278 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5279 (insert-buffer-substring oldbuf start end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5280 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5281 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5282 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5283 The @code{insert-buffer-substring} function copies a string @emph{from} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5284 the buffer specified as its first argument and inserts the string into |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5285 the present buffer. In this case, the argument to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5286 @code{insert-buffer-substring} is the value of the variable created and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5287 bound by the @code{let}, namely the value of @code{oldbuf}, which was |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5288 the current buffer when you gave the @code{append-to-buffer} command. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5289 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5290 After @code{insert-buffer-substring} has done its work, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5291 @code{save-excursion} will restore the action to the original buffer and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5292 @code{append-to-buffer} will have done its job. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5293 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5294 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5295 Written in skeletal form, the workings of the body look like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5296 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5297 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5298 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5299 (let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5300 (save-excursion ; @r{Keep track of buffer.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5301 @var{change-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5302 @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5303 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5304 @var{change-back-to-original-buffer-when-finished} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5305 @var{let-the-local-meaning-of-}@code{oldbuf}@var{-disappear-when-finished} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5306 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5307 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5308 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5309 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5310 In summary, @code{append-to-buffer} works as follows: it saves the value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5311 of the current buffer in the variable called @code{oldbuf}. It gets the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5312 new buffer, creating one if need be, and switches Emacs to it. Using |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5313 the value of @code{oldbuf}, it inserts the region of text from the old |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5314 buffer into the new buffer; and then using @code{save-excursion}, it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5315 brings you back to your original buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5316 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5317 In looking at @code{append-to-buffer}, you have explored a fairly |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5318 complex function. It shows how to use @code{let} and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5319 @code{save-excursion}, and how to change to and come back from another |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5320 buffer. Many function definitions use @code{let}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5321 @code{save-excursion}, and @code{set-buffer} this way. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5322 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5323 @node Buffer Related Review, Buffer Exercises, append-to-buffer, Buffer Walk Through |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5324 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5325 @section Review |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5326 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5327 Here is a brief summary of the various functions discussed in this chapter. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5328 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5329 @table @code |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5330 @item describe-function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5331 @itemx describe-variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5332 Print the documentation for a function or variable. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5333 Conventionally bound to @kbd{C-h f} and @kbd{C-h v}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5334 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5335 @item find-tag |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5336 Find the file containing the source for a function or variable and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5337 switch buffers to it, positioning point at the beginning of the item. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5338 Conventionally bound to @kbd{M-.} (that's a period following the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5339 @key{META} key). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5340 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5341 @item save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5342 Save the location of point and mark and restore their values after the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5343 arguments to @code{save-excursion} have been evaluated. Also, remember |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5344 the current buffer and return to it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5345 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5346 @item push-mark |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5347 Set mark at a location and record the value of the previous mark on the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5348 mark ring. The mark is a location in the buffer that will keep its |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5349 relative position even if text is added to or removed from the buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5350 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5351 @item goto-char |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5352 Set point to the location specified by the value of the argument, which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5353 can be a number, a marker, or an expression that returns the number of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5354 a position, such as @code{(point-min)}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5355 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5356 @item insert-buffer-substring |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5357 Copy a region of text from a buffer that is passed to the function as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5358 an argument and insert the region into the current buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5359 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5360 @item mark-whole-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5361 Mark the whole buffer as a region. Normally bound to @kbd{C-x h}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5362 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5363 @item set-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5364 Switch the attention of Emacs to another buffer, but do not change the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5365 window being displayed. Used when the program rather than a human is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5366 to work on a different buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5367 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5368 @item get-buffer-create |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5369 @itemx get-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5370 Find a named buffer or create one if a buffer of that name does not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5371 exist. The @code{get-buffer} function returns @code{nil} if the named |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5372 buffer does not exist. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5373 @end table |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5374 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5375 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5376 @node Buffer Exercises, , Buffer Related Review, Buffer Walk Through |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5377 @section Exercises |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5378 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5379 @itemize @bullet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5380 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5381 Write your own @code{simplified-end-of-buffer} function definition; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5382 then test it to see whether it works. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5383 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5384 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5385 Use @code{if} and @code{get-buffer} to write a function that prints a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5386 message telling you whether a buffer exists. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5387 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5388 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5389 Using @code{find-tag}, find the source for the @code{copy-to-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5390 function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5391 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5392 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5393 @node More Complex, Narrowing & Widening, Buffer Walk Through, Top |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5394 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5395 @chapter A Few More Complex Functions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5396 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5397 In this chapter, we build on what we have learned in previous chapters |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5398 by looking at more complex functions. The @code{copy-to-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5399 function illustrates use of two @code{save-excursion} expressions in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5400 one definition, while the @code{insert-buffer} function illustrates |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5401 use of an asterisk in an @code{interactive} expression, use of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5402 @code{or}, and the important distinction between a name and the object |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5403 to which the name refers. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5404 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5405 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5406 * copy-to-buffer:: With @code{set-buffer}, @code{get-buffer-create}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5407 * insert-buffer:: Read-only, and with @code{or}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5408 * beginning-of-buffer:: Shows @code{goto-char}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5409 @code{point-min}, and @code{push-mark}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5410 * Second Buffer Related Review:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5411 * optional Exercise:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5412 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5413 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5414 @node copy-to-buffer, insert-buffer, More Complex, More Complex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5415 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5416 @section The Definition of @code{copy-to-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5417 @findex copy-to-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5418 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5419 After understanding how @code{append-to-buffer} works, it is easy to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5420 understand @code{copy-to-buffer}. This function copies text into a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5421 buffer, but instead of adding to the second buffer, it replaces the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5422 previous text in the second buffer. The code for the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5423 @code{copy-to-buffer} function is almost the same as the code for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5424 @code{append-to-buffer}, except that @code{erase-buffer} and a second |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5425 @code{save-excursion} are used. (@xref{append-to-buffer, , The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5426 Definition of @code{append-to-buffer}}, for the description of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5427 @code{append-to-buffer}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5428 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5429 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5430 The body of @code{copy-to-buffer} looks like this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5431 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5432 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5433 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5434 @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5435 (interactive "BCopy to buffer:@: \nr") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5436 (let ((oldbuf (current-buffer))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5437 (save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5438 (set-buffer (get-buffer-create buffer)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5439 (erase-buffer) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5440 (save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5441 (insert-buffer-substring oldbuf start end))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5442 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5443 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5444 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5445 This code is similar to the code in @code{append-to-buffer}: it is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5446 only after changing to the buffer to which the text will be copied |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5447 that the definition for this function diverges from the definition for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5448 @code{append-to-buffer}: the @code{copy-to-buffer} function erases the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5449 buffer's former contents. (This is what is meant by `replacement'; to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5450 replace text, Emacs erases the previous text and then inserts new |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5451 text.) After erasing the previous contents of the buffer, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5452 @code{save-excursion} is used for a second time and the new text is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5453 inserted. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5454 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5455 Why is @code{save-excursion} used twice? Consider again what the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5456 function does. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5457 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5458 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5459 In outline, the body of @code{copy-to-buffer} looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5460 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5461 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5462 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5463 (let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5464 (save-excursion ; @r{First use of @code{save-excursion}.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5465 @var{change-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5466 (erase-buffer) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5467 (save-excursion ; @r{Second use of @code{save-excursion}.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5468 @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer}))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5469 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5470 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5471 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5472 The first use of @code{save-excursion} returns Emacs to the buffer from |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5473 which the text is being copied. That is clear, and is just like its use |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5474 in @code{append-to-buffer}. Why the second use? The reason is that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5475 @code{insert-buffer-substring} always leaves point at the @emph{end} of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5476 the region being inserted. The second @code{save-excursion} causes |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5477 Emacs to leave point at the beginning of the text being inserted. In |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5478 most circumstances, users prefer to find point at the beginning of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5479 inserted text. (Of course, the @code{copy-to-buffer} function returns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5480 the user to the original buffer when done---but if the user @emph{then} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5481 switches to the copied-to buffer, point will go to the beginning of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5482 text. Thus, this use of a second @code{save-excursion} is a little |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5483 nicety.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5484 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5485 @node insert-buffer, beginning-of-buffer, copy-to-buffer, More Complex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5486 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5487 @section The Definition of @code{insert-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5488 @findex insert-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5489 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5490 @code{insert-buffer} is yet another buffer-related function. This |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5491 command copies another buffer @emph{into} the current buffer. It is the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5492 reverse of @code{append-to-buffer} or @code{copy-to-buffer}, since they |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5493 copy a region of text @emph{from} the current buffer to another buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5494 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5495 In addition, this code illustrates the use of @code{interactive} with a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5496 buffer that might be @dfn{read-only} and the important distinction |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5497 between the name of an object and the object actually referred to. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5498 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5499 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5500 * insert-buffer code:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5501 * insert-buffer interactive:: When you can read, but not write. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5502 * insert-buffer body:: The body has an @code{or} and a @code{let}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5503 * if & or:: Using an @code{if} instead of an @code{or}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5504 * Insert or:: How the @code{or} expression works. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5505 * Insert let:: Two @code{save-excursion} expressions. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5506 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5507 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5508 @node insert-buffer code, insert-buffer interactive, insert-buffer, insert-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5509 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5510 @unnumberedsubsec The Code for @code{insert-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5511 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5512 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5513 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5514 Here is the code: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5515 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5516 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5517 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5518 (defun insert-buffer (buffer) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5519 "Insert after point the contents of BUFFER. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5520 Puts mark after the inserted text. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5521 BUFFER may be a buffer or a buffer name." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5522 (interactive "*bInsert buffer:@: ") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5523 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5524 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5525 (or (bufferp buffer) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5526 (setq buffer (get-buffer buffer))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5527 (let (start end newmark) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5528 (save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5529 (save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5530 (set-buffer buffer) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5531 (setq start (point-min) end (point-max))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5532 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5533 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5534 (insert-buffer-substring buffer start end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5535 (setq newmark (point))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5536 (push-mark newmark))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5537 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5538 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5539 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5540 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5541 As with other function definitions, you can use a template to see an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5542 outline of the function: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5543 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5544 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5545 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5546 (defun insert-buffer (buffer) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5547 "@var{documentation}@dots{}" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5548 (interactive "*bInsert buffer:@: ") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5549 @var{body}@dots{}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5550 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5551 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5552 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5553 @node insert-buffer interactive, insert-buffer body, insert-buffer code, insert-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5554 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5555 @subsection The Interactive Expression in @code{insert-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5556 @findex interactive, @r{example use of} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5557 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5558 In @code{insert-buffer}, the argument to the @code{interactive} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5559 declaration has two parts, an asterisk, @samp{*}, and @samp{bInsert |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5560 buffer:@: }. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5561 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5562 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5563 * Read-only buffer:: When a buffer cannot be modified. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5564 * b for interactive:: An existing buffer or else its name. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5565 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5566 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5567 @node Read-only buffer, b for interactive, insert-buffer interactive, insert-buffer interactive |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5568 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5569 @unnumberedsubsubsec A Read-only Buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5570 @cindex Read-only buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5571 @cindex Asterisk for read-only buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5572 @findex * @r{for read-only buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5573 |
44899
ebddb2618c17
Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents:
43431
diff
changeset
|
5574 The asterisk is for the situation when the current buffer is a |
ebddb2618c17
Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents:
43431
diff
changeset
|
5575 read-only buffer---a buffer that cannot be modified. If |
ebddb2618c17
Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents:
43431
diff
changeset
|
5576 @code{insert-buffer} is called when the current buffer is read-only, a |
ebddb2618c17
Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents:
43431
diff
changeset
|
5577 message to this effect is printed in the echo area and the terminal |
ebddb2618c17
Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents:
43431
diff
changeset
|
5578 may beep or blink at you; you will not be permitted to insert anything |
ebddb2618c17
Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents:
43431
diff
changeset
|
5579 into current buffer. The asterisk does not need to be followed by a |
ebddb2618c17
Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents:
43431
diff
changeset
|
5580 newline to separate it from the next argument. |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5581 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5582 @node b for interactive, , Read-only buffer, insert-buffer interactive |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5583 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5584 @unnumberedsubsubsec @samp{b} in an Interactive Expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5585 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5586 The next argument in the interactive expression starts with a lower |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5587 case @samp{b}. (This is different from the code for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5588 @code{append-to-buffer}, which uses an upper-case @samp{B}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5589 @xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5590 The lower-case @samp{b} tells the Lisp interpreter that the argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5591 for @code{insert-buffer} should be an existing buffer or else its |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5592 name. (The upper-case @samp{B} option provides for the possibility |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5593 that the buffer does not exist.) Emacs will prompt you for the name |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5594 of the buffer, offering you a default buffer, with name completion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5595 enabled. If the buffer does not exist, you receive a message that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5596 says ``No match''; your terminal may beep at you as well. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5597 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5598 @node insert-buffer body, if & or, insert-buffer interactive, insert-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5599 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5600 @subsection The Body of the @code{insert-buffer} Function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5601 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5602 The body of the @code{insert-buffer} function has two major parts: an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5603 @code{or} expression and a @code{let} expression. The purpose of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5604 @code{or} expression is to ensure that the argument @code{buffer} is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5605 bound to a buffer and not just the name of a buffer. The body of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5606 @code{let} expression contains the code which copies the other buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5607 into the current buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5608 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5609 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5610 In outline, the two expressions fit into the @code{insert-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5611 function like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5612 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5613 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5614 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5615 (defun insert-buffer (buffer) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5616 "@var{documentation}@dots{}" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5617 (interactive "*bInsert buffer:@: ") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5618 (or @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5619 @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5620 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5621 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5622 (let (@var{varlist}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5623 @var{body-of-}@code{let}@dots{} ) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5624 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5625 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5626 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5627 To understand how the @code{or} expression ensures that the argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5628 @code{buffer} is bound to a buffer and not to the name of a buffer, it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5629 is first necessary to understand the @code{or} function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5630 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5631 Before doing this, let me rewrite this part of the function using |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5632 @code{if} so that you can see what is done in a manner that will be familiar. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5633 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5634 @node if & or, Insert or, insert-buffer body, insert-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5635 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5636 @subsection @code{insert-buffer} With an @code{if} Instead of an @code{or} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5637 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5638 The job to be done is to make sure the value of @code{buffer} is a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5639 buffer itself and not the name of a buffer. If the value is the name, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5640 then the buffer itself must be got. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5641 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5642 You can imagine yourself at a conference where an usher is wandering |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5643 around holding a list with your name on it and looking for you: the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5644 usher is ``bound'' to your name, not to you; but when the usher finds |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5645 you and takes your arm, the usher becomes ``bound'' to you. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5646 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5647 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5648 In Lisp, you might describe this situation like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5649 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5650 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5651 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5652 (if (not (holding-on-to-guest)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5653 (find-and-take-arm-of-guest)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5654 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5655 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5656 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5657 We want to do the same thing with a buffer---if we do not have the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5658 buffer itself, we want to get it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5659 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5660 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5661 Using a predicate called @code{bufferp} that tells us whether we have a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5662 buffer (rather than its name), we can write the code like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5663 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5664 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5665 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5666 (if (not (bufferp buffer)) ; @r{if-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5667 (setq buffer (get-buffer buffer))) ; @r{then-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5668 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5669 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5670 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5671 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5672 Here, the true-or-false-test of the @code{if} expression is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5673 @w{@code{(not (bufferp buffer))}}; and the then-part is the expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5674 @w{@code{(setq buffer (get-buffer buffer))}}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5675 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5676 In the test, the function @code{bufferp} returns true if its argument is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5677 a buffer---but false if its argument is the name of the buffer. (The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5678 last character of the function name @code{bufferp} is the character |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5679 @samp{p}; as we saw earlier, such use of @samp{p} is a convention that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5680 indicates that the function is a predicate, which is a term that means |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5681 that the function will determine whether some property is true or false. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5682 @xref{Wrong Type of Argument, , Using the Wrong Type Object as an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5683 Argument}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5684 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5685 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5686 The function @code{not} precedes the expression @code{(bufferp buffer)}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5687 so the true-or-false-test looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5688 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5689 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5690 (not (bufferp buffer)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5691 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5692 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5693 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5694 @code{not} is a function that returns true if its argument is false |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5695 and false if its argument is true. So if @code{(bufferp buffer)} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5696 returns true, the @code{not} expression returns false and vice-versa: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5697 what is ``not true'' is false and what is ``not false'' is true. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5698 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5699 Using this test, the @code{if} expression works as follows: when the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5700 value of the variable @code{buffer} is actually a buffer rather then |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5701 its name, the true-or-false-test returns false and the @code{if} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5702 expression does not evaluate the then-part. This is fine, since we do |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5703 not need to do anything to the variable @code{buffer} if it really is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5704 a buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5705 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5706 On the other hand, when the value of @code{buffer} is not a buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5707 itself, but the name of a buffer, the true-or-false-test returns true |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5708 and the then-part of the expression is evaluated. In this case, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5709 then-part is @code{(setq buffer (get-buffer buffer))}. This |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5710 expression uses the @code{get-buffer} function to return an actual |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5711 buffer itself, given its name. The @code{setq} then sets the variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5712 @code{buffer} to the value of the buffer itself, replacing its previous |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5713 value (which was the name of the buffer). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5714 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5715 @node Insert or, Insert let, if & or, insert-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5716 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5717 @subsection The @code{or} in the Body |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5718 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5719 The purpose of the @code{or} expression in the @code{insert-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5720 function is to ensure that the argument @code{buffer} is bound to a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5721 buffer and not just to the name of a buffer. The previous section shows |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5722 how the job could have been done using an @code{if} expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5723 However, the @code{insert-buffer} function actually uses @code{or}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5724 To understand this, it is necessary to understand how @code{or} works. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5725 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5726 @findex or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5727 An @code{or} function can have any number of arguments. It evaluates |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5728 each argument in turn and returns the value of the first of its |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5729 arguments that is not @code{nil}. Also, and this is a crucial feature |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5730 of @code{or}, it does not evaluate any subsequent arguments after |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5731 returning the first non-@code{nil} value. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5732 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5733 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5734 The @code{or} expression looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5735 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5736 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5737 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5738 (or (bufferp buffer) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5739 (setq buffer (get-buffer buffer))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5740 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5741 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5742 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5743 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5744 The first argument to @code{or} is the expression @code{(bufferp buffer)}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5745 This expression returns true (a non-@code{nil} value) if the buffer is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5746 actually a buffer, and not just the name of a buffer. In the @code{or} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5747 expression, if this is the case, the @code{or} expression returns this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5748 true value and does not evaluate the next expression---and this is fine |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5749 with us, since we do not want to do anything to the value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5750 @code{buffer} if it really is a buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5751 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5752 On the other hand, if the value of @code{(bufferp buffer)} is @code{nil}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5753 which it will be if the value of @code{buffer} is the name of a buffer, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5754 the Lisp interpreter evaluates the next element of the @code{or} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5755 expression. This is the expression @code{(setq buffer (get-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5756 buffer))}. This expression returns a non-@code{nil} value, which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5757 is the value to which it sets the variable @code{buffer}---and this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5758 value is a buffer itself, not the name of a buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5759 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5760 The result of all this is that the symbol @code{buffer} is always |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5761 bound to a buffer itself rather than to the name of a buffer. All |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5762 this is necessary because the @code{set-buffer} function in a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5763 following line only works with a buffer itself, not with the name to a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5764 buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5765 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5766 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5767 Incidentally, using @code{or}, the situation with the usher would be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5768 written like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5769 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5770 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5771 (or (holding-on-to-guest) (find-and-take-arm-of-guest)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5772 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5773 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5774 @node Insert let, , Insert or, insert-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5775 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5776 @subsection The @code{let} Expression in @code{insert-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5777 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5778 After ensuring that the variable @code{buffer} refers to a buffer itself |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5779 and not just to the name of a buffer, the @code{insert-buffer function} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5780 continues with a @code{let} expression. This specifies three local |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5781 variables, @code{start}, @code{end}, and @code{newmark} and binds them |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5782 to the initial value @code{nil}. These variables are used inside the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5783 remainder of the @code{let} and temporarily hide any other occurrence of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5784 variables of the same name in Emacs until the end of the @code{let}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5785 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5786 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5787 The body of the @code{let} contains two @code{save-excursion} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5788 expressions. First, we will look at the inner @code{save-excursion} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5789 expression in detail. The expression looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5790 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5791 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5792 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5793 (save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5794 (set-buffer buffer) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5795 (setq start (point-min) end (point-max))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5796 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5797 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5798 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5799 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5800 The expression @code{(set-buffer buffer)} changes Emacs' attention |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5801 from the current buffer to the one from which the text will copied. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5802 In that buffer, the variables @code{start} and @code{end} are set to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5803 the beginning and end of the buffer, using the commands |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5804 @code{point-min} and @code{point-max}. Note that we have here an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5805 illustration of how @code{setq} is able to set two variables in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5806 same expression. The first argument of @code{setq} is set to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5807 value of its second, and its third argument is set to the value of its |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5808 fourth. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5809 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5810 After the body of the inner @code{save-excursion} is evaluated, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5811 @code{save-excursion} restores the original buffer, but @code{start} and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5812 @code{end} remain set to the values of the beginning and end of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5813 buffer from which the text will be copied. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5814 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5815 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5816 The outer @code{save-excursion} expression looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5817 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5818 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5819 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5820 (save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5821 (@var{inner-}@code{save-excursion}@var{-expression} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5822 (@var{go-to-new-buffer-and-set-}@code{start}@var{-and-}@code{end}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5823 (insert-buffer-substring buffer start end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5824 (setq newmark (point))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5825 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5826 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5827 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5828 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5829 The @code{insert-buffer-substring} function copies the text |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5830 @emph{into} the current buffer @emph{from} the region indicated by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5831 @code{start} and @code{end} in @code{buffer}. Since the whole of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5832 second buffer lies between @code{start} and @code{end}, the whole of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5833 the second buffer is copied into the buffer you are editing. Next, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5834 the value of point, which will be at the end of the inserted text, is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5835 recorded in the variable @code{newmark}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5836 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5837 After the body of the outer @code{save-excursion} is evaluated, point |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5838 and mark are relocated to their original places. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5839 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5840 However, it is convenient to locate a mark at the end of the newly |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5841 inserted text and locate point at its beginning. The @code{newmark} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5842 variable records the end of the inserted text. In the last line of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5843 the @code{let} expression, the @code{(push-mark newmark)} expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5844 function sets a mark to this location. (The previous location of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5845 mark is still accessible; it is recorded on the mark ring and you can |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5846 go back to it with @kbd{C-u C-@key{SPC}}.) Meanwhile, point is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5847 located at the beginning of the inserted text, which is where it was |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5848 before you called the insert function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5849 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5850 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5851 The whole @code{let} expression looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5852 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5853 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5854 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5855 (let (start end newmark) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5856 (save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5857 (save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5858 (set-buffer buffer) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5859 (setq start (point-min) end (point-max))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5860 (insert-buffer-substring buffer start end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5861 (setq newmark (point))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5862 (push-mark newmark)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5863 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5864 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5865 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5866 Like the @code{append-to-buffer} function, the @code{insert-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5867 function uses @code{let}, @code{save-excursion}, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5868 @code{set-buffer}. In addition, the function illustrates one way to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5869 use @code{or}. All these functions are building blocks that we will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5870 find and use again and again. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5871 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5872 @node beginning-of-buffer, Second Buffer Related Review, insert-buffer, More Complex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5873 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5874 @section Complete Definition of @code{beginning-of-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5875 @findex beginning-of-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5876 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5877 The basic structure of the @code{beginning-of-buffer} function has |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5878 already been discussed. (@xref{simplified-beginning-of-buffer, , A |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5879 Simplified @code{beginning-of-buffer} Definition}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5880 This section describes the complex part of the definition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5881 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5882 As previously described, when invoked without an argument, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5883 @code{beginning-of-buffer} moves the cursor to the beginning of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5884 buffer, leaving the mark at the previous position. However, when the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5885 command is invoked with a number between one and ten, the function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5886 considers that number to be a fraction of the length of the buffer, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5887 measured in tenths, and Emacs moves the cursor that fraction of the way |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5888 from the beginning of the buffer. Thus, you can either call this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5889 function with the key command @kbd{M-<}, which will move the cursor to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5890 the beginning of the buffer, or with a key command such as @kbd{C-u 7 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5891 M-<} which will move the cursor to a point 70% of the way through the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5892 buffer. If a number bigger than ten is used for the argument, it moves |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5893 to the end of the buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5894 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5895 The @code{beginning-of-buffer} function can be called with or without an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5896 argument. The use of the argument is optional. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5897 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5898 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5899 * Optional Arguments:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5900 * beginning-of-buffer opt arg:: Example with optional argument. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5901 * beginning-of-buffer complete:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5902 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5903 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5904 @node Optional Arguments, beginning-of-buffer opt arg, beginning-of-buffer, beginning-of-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5905 @subsection Optional Arguments |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5906 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5907 Unless told otherwise, Lisp expects that a function with an argument in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5908 its function definition will be called with a value for that argument. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5909 If that does not happen, you get an error and a message that says |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5910 @samp{Wrong number of arguments}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5911 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5912 @cindex Optional arguments |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5913 @cindex Keyword |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5914 @findex optional |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5915 However, optional arguments are a feature of Lisp: a @dfn{keyword} may |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5916 be used to tell the Lisp interpreter that an argument is optional. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5917 The keyword is @code{&optional}. (The @samp{&} in front of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5918 @samp{optional} is part of the keyword.) In a function definition, if |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5919 an argument follows the keyword @code{&optional}, a value does not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5920 need to be passed to that argument when the function is called. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5921 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5922 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5923 The first line of the function definition of @code{beginning-of-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5924 therefore looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5925 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5926 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5927 (defun beginning-of-buffer (&optional arg) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5928 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5929 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5930 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5931 In outline, the whole function looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5932 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5933 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5934 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5935 (defun beginning-of-buffer (&optional arg) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5936 "@var{documentation}@dots{}" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5937 (interactive "P") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5938 (push-mark) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5939 (goto-char |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5940 (@var{if-there-is-an-argument} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5941 @var{figure-out-where-to-go} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5942 @var{else-go-to} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5943 (point-min)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5944 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5945 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5946 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5947 The function is similar to the @code{simplified-beginning-of-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5948 function except that the @code{interactive} expression has @code{"P"} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5949 as an argument and the @code{goto-char} function is followed by an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5950 if-then-else expression that figures out where to put the cursor if |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5951 there is an argument. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5952 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5953 The @code{"P"} in the @code{interactive} expression tells Emacs to pass |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5954 a prefix argument, if there is one, to the function. A prefix argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5955 is made by typing the @key{META} key followed by a number, or by typing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5956 @kbd{C-u} and then a number (if you don't type a number, @kbd{C-u} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5957 defaults to 4). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5958 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5959 The true-or-false-test of the @code{if} expression is simple: it is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5960 simply the argument @code{arg}. If @code{arg} has a value that is not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5961 @code{nil}, which will be the case if @code{beginning-of-buffer} is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5962 called with an argument, then this true-or-false-test will return true |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5963 and the then-part of the @code{if} expression will be evaluated. On the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5964 other hand, if @code{beginning-of-buffer} is not called with an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5965 argument, the value of @code{arg} will be @code{nil} and the else-part |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5966 of the @code{if} expression will be evaluated. The else-part is simply |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5967 @code{point-min}, and when this is the outcome, the whole |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5968 @code{goto-char} expression is @code{(goto-char (point-min))}, which is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5969 how we saw the @code{beginning-of-buffer} function in its simplified |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5970 form. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5971 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5972 @node beginning-of-buffer opt arg, beginning-of-buffer complete, Optional Arguments, beginning-of-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5973 @subsection @code{beginning-of-buffer} with an Argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5974 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5975 When @code{beginning-of-buffer} is called with an argument, an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5976 expression is evaluated which calculates what value to pass to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5977 @code{goto-char}. This expression is rather complicated at first sight. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5978 It includes an inner @code{if} expression and much arithmetic. It looks |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5979 like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5980 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5981 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5982 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5983 (if (> (buffer-size) 10000) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5984 ;; @r{Avoid overflow for large buffer sizes!} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5985 (* (prefix-numeric-value arg) (/ (buffer-size) 10)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5986 (/ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5987 (+ 10 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5988 (* |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5989 (buffer-size) (prefix-numeric-value arg))) 10)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5990 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5991 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5992 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5993 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5994 * Disentangle beginning-of-buffer:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5995 * Large buffer case:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5996 * Small buffer case:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5997 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5998 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
5999 @node Disentangle beginning-of-buffer, Large buffer case, beginning-of-buffer opt arg, beginning-of-buffer opt arg |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6000 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6001 @unnumberedsubsubsec Disentangle @code{beginning-of-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6002 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6003 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6004 Like other complex-looking expressions, the conditional expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6005 within @code{beginning-of-buffer} can be disentangled by looking at it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6006 as parts of a template, in this case, the template for an if-then-else |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6007 expression. In skeletal form, the expression looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6008 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6009 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6010 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6011 (if (@var{buffer-is-large} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6012 @var{divide-buffer-size-by-10-and-multiply-by-arg} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6013 @var{else-use-alternate-calculation} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6014 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6015 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6016 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6017 The true-or-false-test of this inner @code{if} expression checks the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6018 size of the buffer. The reason for this is that the old Version 18 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6019 Emacs used numbers that are no bigger than eight million or so |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6020 and in the computation that followed, the programmer feared that Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6021 might try to use over-large numbers if the buffer were large. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6022 term `overflow', mentioned in the comment, means numbers that are over |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6023 large. Version 21 Emacs uses larger numbers, but this code has not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6024 been touched, if only because people now look at buffers that are far, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6025 far larger than ever before. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6026 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6027 There are two cases: if the buffer is large and if it is not. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6028 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6029 @node Large buffer case, Small buffer case, Disentangle beginning-of-buffer, beginning-of-buffer opt arg |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6030 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6031 @unnumberedsubsubsec What happens in a large buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6032 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6033 In @code{beginning-of-buffer}, the inner @code{if} expression tests |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6034 whether the size of the buffer is greater than 10,000 characters. To do |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6035 this, it uses the @code{>} function and the @code{buffer-size} function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6036 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6037 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6038 The line looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6039 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6040 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6041 (if (> (buffer-size) 10000) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6042 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6043 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6044 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6045 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6046 When the buffer is large, the then-part of the @code{if} expression is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6047 evaluated. It reads like this (after formatting for easy reading): |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6048 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6049 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6050 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6051 (* |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6052 (prefix-numeric-value arg) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6053 (/ (buffer-size) 10)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6054 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6055 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6056 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6057 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6058 This expression is a multiplication, with two arguments to the function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6059 @code{*}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6060 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6061 The first argument is @code{(prefix-numeric-value arg)}. When |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6062 @code{"P"} is used as the argument for @code{interactive}, the value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6063 passed to the function as its argument is passed a ``raw prefix |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6064 argument'', and not a number. (It is a number in a list.) To perform |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6065 the arithmetic, a conversion is necessary, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6066 @code{prefix-numeric-value} does the job. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6067 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6068 @findex / @r{(division)} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6069 @cindex Division |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6070 The second argument is @code{(/ (buffer-size) 10)}. This expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6071 divides the numeric value of the buffer by ten. This produces a number |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6072 that tells how many characters make up one tenth of the buffer size. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6073 (In Lisp, @code{/} is used for division, just as @code{*} is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6074 used for multiplication.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6075 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6076 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6077 In the multiplication expression as a whole, this amount is multiplied |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6078 by the value of the prefix argument---the multiplication looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6079 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6080 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6081 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6082 (* @var{numeric-value-of-prefix-arg} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6083 @var{number-of-characters-in-one-tenth-of-the-buffer}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6084 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6085 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6086 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6087 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6088 If, for example, the prefix argument is @samp{7}, the one-tenth value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6089 will be multiplied by 7 to give a position 70% of the way through the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6090 buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6091 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6092 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6093 The result of all this is that if the buffer is large, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6094 @code{goto-char} expression reads like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6095 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6096 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6097 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6098 (goto-char (* (prefix-numeric-value arg) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6099 (/ (buffer-size) 10))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6100 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6101 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6102 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6103 This puts the cursor where we want it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6104 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6105 @node Small buffer case, , Large buffer case, beginning-of-buffer opt arg |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6106 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6107 @unnumberedsubsubsec What happens in a small buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6108 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6109 If the buffer contains fewer than 10,000 characters, a slightly |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6110 different computation is performed. You might think this is not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6111 necessary, since the first computation could do the job. However, in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6112 a small buffer, the first method may not put the cursor on exactly the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6113 desired line; the second method does a better job. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6114 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6115 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6116 The code looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6117 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6118 @c Keep this on one line. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6119 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6120 (/ (+ 10 (* (buffer-size) (prefix-numeric-value arg))) 10)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6121 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6122 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6123 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6124 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6125 This is code in which you figure out what happens by discovering how the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6126 functions are embedded in parentheses. It is easier to read if you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6127 reformat it with each expression indented more deeply than its |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6128 enclosing expression: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6129 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6130 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6131 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6132 (/ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6133 (+ 10 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6134 (* |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6135 (buffer-size) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6136 (prefix-numeric-value arg))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6137 10)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6138 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6139 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6140 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6141 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6142 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6143 Looking at parentheses, we see that the innermost operation is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6144 @code{(prefix-numeric-value arg)}, which converts the raw argument to a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6145 number. This number is multiplied by the buffer size in the following |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6146 expression: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6147 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6148 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6149 (* (buffer-size) (prefix-numeric-value arg) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6150 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6151 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6152 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6153 This multiplication creates a number that may be larger than the size of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6154 the buffer---seven times larger if the argument is 7, for example. Ten |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6155 is then added to this number and finally the large number is divided by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6156 ten to provide a value that is one character larger than the percentage |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6157 position in the buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6158 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6159 The number that results from all this is passed to @code{goto-char} and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6160 the cursor is moved to that point. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6161 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6162 @node beginning-of-buffer complete, , beginning-of-buffer opt arg, beginning-of-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6163 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6164 @subsection The Complete @code{beginning-of-buffer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6165 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6166 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6167 Here is the complete text of the @code{beginning-of-buffer} function: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6168 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6169 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6170 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6171 (defun beginning-of-buffer (&optional arg) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6172 "Move point to the beginning of the buffer; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6173 leave mark at previous position. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6174 With arg N, put point N/10 of the way |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6175 from the true beginning. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6176 Don't use this in Lisp programs! |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6177 \(goto-char (point-min)) is faster |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6178 and does not set the mark." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6179 (interactive "P") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6180 (push-mark) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6181 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6182 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6183 (goto-char |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6184 (if arg |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6185 (if (> (buffer-size) 10000) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6186 ;; @r{Avoid overflow for large buffer sizes!} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6187 (* (prefix-numeric-value arg) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6188 (/ (buffer-size) 10)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6189 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6190 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6191 (/ (+ 10 (* (buffer-size) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6192 (prefix-numeric-value arg))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6193 10)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6194 (point-min))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6195 (if arg (forward-line 1))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6196 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6197 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6198 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6199 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6200 Except for two small points, the previous discussion shows how this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6201 function works. The first point deals with a detail in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6202 documentation string, and the second point concerns the last line of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6203 the function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6204 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6205 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6206 In the documentation string, there is reference to an expression: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6207 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6208 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6209 \(goto-char (point-min)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6210 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6211 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6212 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6213 A @samp{\} is used before the first parenthesis of this expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6214 This @samp{\} tells the Lisp interpreter that the expression should be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6215 printed as shown in the documentation rather than evaluated as a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6216 symbolic expression, which is what it looks like. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6217 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6218 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6219 Finally, the last line of the @code{beginning-of-buffer} command says to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6220 move point to the beginning of the next line if the command is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6221 invoked with an argument: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6222 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6223 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6224 (if arg (forward-line 1))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6225 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6226 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6227 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6228 This puts the cursor at the beginning of the first line after the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6229 appropriate tenths position in the buffer. This is a flourish that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6230 means that the cursor is always located @emph{at least} the requested |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6231 tenths of the way through the buffer, which is a nicety that is, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6232 perhaps, not necessary, but which, if it did not occur, would be sure to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6233 draw complaints. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6234 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6235 @node Second Buffer Related Review, optional Exercise, beginning-of-buffer, More Complex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6236 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6237 @section Review |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6238 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6239 Here is a brief summary of some of the topics covered in this chapter. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6240 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6241 @table @code |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6242 @item or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6243 Evaluate each argument in sequence, and return the value of the first |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6244 argument that is not @code{nil}; if none return a value that is not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6245 @code{nil}, return @code{nil}. In brief, return the first true value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6246 of the arguments; return a true value if one @emph{or} any of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6247 other are true. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6248 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6249 @item and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6250 Evaluate each argument in sequence, and if any are @code{nil}, return |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6251 @code{nil}; if none are @code{nil}, return the value of the last |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6252 argument. In brief, return a true value only if all the arguments are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6253 true; return a true value if one @emph{and} each of the others is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6254 true. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6255 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6256 @item &optional |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6257 A keyword used to indicate that an argument to a function definition |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6258 is optional; this means that the function can be evaluated without the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6259 argument, if desired. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6260 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6261 @item prefix-numeric-value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6262 Convert the `raw prefix argument' produced by @code{(interactive |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6263 "P")} to a numeric value. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6264 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6265 @item forward-line |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6266 Move point forward to the beginning of the next line, or if the argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6267 is greater than one, forward that many lines. If it can't move as far |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6268 forward as it is supposed to, @code{forward-line} goes forward as far as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6269 it can and then returns a count of the number of additional lines it was |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6270 supposed to move but couldn't. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6271 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6272 @item erase-buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6273 Delete the entire contents of the current buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6274 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6275 @item bufferp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6276 Return @code{t} if its argument is a buffer; otherwise return @code{nil}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6277 @end table |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6278 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6279 @node optional Exercise, , Second Buffer Related Review, More Complex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6280 @section @code{optional} Argument Exercise |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6281 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6282 Write an interactive function with an optional argument that tests |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6283 whether its argument, a number, is greater or less than the value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6284 @code{fill-column}, and tells you which, in a message. However, if you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6285 do not pass an argument to the function, use 56 as a default value. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6286 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6287 @node Narrowing & Widening, car cdr & cons, More Complex, Top |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6288 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6289 @chapter Narrowing and Widening |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6290 @cindex Focusing attention (narrowing) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6291 @cindex Narrowing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6292 @cindex Widening |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6293 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6294 Narrowing is a feature of Emacs that makes it possible for you to focus |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6295 on a specific part of a buffer, and work without accidentally changing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6296 other parts. Narrowing is normally disabled since it can confuse |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6297 novices. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6298 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6299 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6300 * Narrowing advantages:: The advantages of narrowing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6301 * save-restriction:: The @code{save-restriction} special form. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6302 * what-line:: The number of the line that point is on. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6303 * narrow Exercise:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6304 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6305 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6306 @node Narrowing advantages, save-restriction, Narrowing & Widening, Narrowing & Widening |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6307 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6308 @unnumberedsec The Advantages of Narrowing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6309 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6310 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6311 With narrowing, the rest of a buffer is made invisible, as if it weren't |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6312 there. This is an advantage if, for example, you want to replace a word |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6313 in one part of a buffer but not in another: you narrow to the part you want |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6314 and the replacement is carried out only in that section, not in the rest |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6315 of the buffer. Searches will only work within a narrowed region, not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6316 outside of one, so if you are fixing a part of a document, you can keep |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6317 yourself from accidentally finding parts you do not need to fix by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6318 narrowing just to the region you want. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6319 (The key binding for @code{narrow-to-region} is @kbd{C-x n n}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6320 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6321 However, narrowing does make the rest of the buffer invisible, which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6322 can scare people who inadvertently invoke narrowing and think they |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6323 have deleted a part of their file. Moreover, the @code{undo} command |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6324 (which is usually bound to @kbd{C-x u}) does not turn off narrowing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6325 (nor should it), so people can become quite desperate if they do not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6326 know that they can return the rest of a buffer to visibility with the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6327 @code{widen} command. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6328 (The key binding for @code{widen} is @kbd{C-x n w}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6329 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6330 Narrowing is just as useful to the Lisp interpreter as to a human. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6331 Often, an Emacs Lisp function is designed to work on just part of a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6332 buffer; or conversely, an Emacs Lisp function needs to work on all of a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6333 buffer that has been narrowed. The @code{what-line} function, for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6334 example, removes the narrowing from a buffer, if it has any narrowing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6335 and when it has finished its job, restores the narrowing to what it was. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6336 On the other hand, the @code{count-lines} function, which is called by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6337 @code{what-line}, uses narrowing to restrict itself to just that portion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6338 of the buffer in which it is interested and then restores the previous |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6339 situation. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6340 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6341 @node save-restriction, what-line, Narrowing advantages, Narrowing & Widening |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6342 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6343 @section The @code{save-restriction} Special Form |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6344 @findex save-restriction |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6345 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6346 In Emacs Lisp, you can use the @code{save-restriction} special form to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6347 keep track of whatever narrowing is in effect, if any. When the Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6348 interpreter meets with @code{save-restriction}, it executes the code |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6349 in the body of the @code{save-restriction} expression, and then undoes |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6350 any changes to narrowing that the code caused. If, for example, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6351 buffer is narrowed and the code that follows @code{save-restriction} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6352 gets rid of the narrowing, @code{save-restriction} returns the buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6353 to its narrowed region afterwards. In the @code{what-line} command, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6354 any narrowing the buffer may have is undone by the @code{widen} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6355 command that immediately follows the @code{save-restriction} command. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6356 Any original narrowing is restored just before the completion of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6357 function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6358 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6359 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6360 The template for a @code{save-restriction} expression is simple: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6361 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6362 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6363 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6364 (save-restriction |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6365 @var{body}@dots{} ) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6366 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6367 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6368 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6369 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6370 The body of the @code{save-restriction} is one or more expressions that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6371 will be evaluated in sequence by the Lisp interpreter. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6372 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6373 Finally, a point to note: when you use both @code{save-excursion} and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6374 @code{save-restriction}, one right after the other, you should use |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6375 @code{save-excursion} outermost. If you write them in reverse order, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6376 you may fail to record narrowing in the buffer to which Emacs switches |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6377 after calling @code{save-excursion}. Thus, when written together, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6378 @code{save-excursion} and @code{save-restriction} should be written |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6379 like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6380 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6381 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6382 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6383 (save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6384 (save-restriction |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6385 @var{body}@dots{})) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6386 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6387 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6388 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6389 In other circumstances, when not written together, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6390 @code{save-excursion} and @code{save-restriction} special forms must |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6391 be written in the order appropriate to the function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6392 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6393 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6394 For example, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6395 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6396 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6397 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6398 (save-restriction |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6399 (widen) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6400 (save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6401 @var{body}@dots{})) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6402 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6403 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6404 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6405 @node what-line, narrow Exercise, save-restriction, Narrowing & Widening |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6406 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6407 @section @code{what-line} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6408 @findex what-line |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6409 @cindex Widening, example of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6410 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6411 The @code{what-line} command tells you the number of the line in which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6412 the cursor is located. The function illustrates the use of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6413 @code{save-restriction} and @code{save-excursion} commands. Here is the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6414 text of the function in full: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6415 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6416 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6417 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6418 (defun what-line () |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6419 "Print the current line number (in the buffer) of point." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6420 (interactive) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6421 (save-restriction |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6422 (widen) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6423 (save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6424 (beginning-of-line) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6425 (message "Line %d" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6426 (1+ (count-lines 1 (point))))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6427 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6428 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6429 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6430 The function has a documentation line and is interactive, as you would |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6431 expect. The next two lines use the functions @code{save-restriction} and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6432 @code{widen}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6433 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6434 The @code{save-restriction} special form notes whatever narrowing is in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6435 effect, if any, in the current buffer and restores that narrowing after |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6436 the code in the body of the @code{save-restriction} has been evaluated. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6437 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6438 The @code{save-restriction} special form is followed by @code{widen}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6439 This function undoes any narrowing the current buffer may have had |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6440 when @code{what-line} was called. (The narrowing that was there is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6441 the narrowing that @code{save-restriction} remembers.) This widening |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6442 makes it possible for the line counting commands to count from the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6443 beginning of the buffer. Otherwise, they would have been limited to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6444 counting within the accessible region. Any original narrowing is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6445 restored just before the completion of the function by the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6446 @code{save-restriction} special form. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6447 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6448 The call to @code{widen} is followed by @code{save-excursion}, which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6449 saves the location of the cursor (i.e., of point) and of the mark, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6450 restores them after the code in the body of the @code{save-excursion} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6451 uses the @code{beginning-of-line} function to move point. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6452 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6453 (Note that the @code{(widen)} expression comes between the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6454 @code{save-restriction} and @code{save-excursion} special forms. When |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6455 you write the two @code{save- @dots{}} expressions in sequence, write |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6456 @code{save-excursion} outermost.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6457 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6458 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6459 The last two lines of the @code{what-line} function are functions to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6460 count the number of lines in the buffer and then print the number in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6461 echo area. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6462 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6463 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6464 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6465 (message "Line %d" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6466 (1+ (count-lines 1 (point))))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6467 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6468 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6469 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6470 The @code{message} function prints a one-line message at the bottom of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6471 Emacs screen. The first argument is inside of quotation marks and is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6472 printed as a string of characters. However, it may contain @samp{%d}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6473 @samp{%s}, or @samp{%c} to print arguments that follow the string. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6474 @samp{%d} prints the argument as a decimal, so the message will say |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6475 something such as @samp{Line 243}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6476 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6477 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6478 The number that is printed in place of the @samp{%d} is computed by the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6479 last line of the function: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6480 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6481 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6482 (1+ (count-lines 1 (point))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6483 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6484 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6485 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6486 What this does is count the lines from the first position of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6487 buffer, indicated by the @code{1}, up to @code{(point)}, and then add |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6488 one to that number. (The @code{1+} function adds one to its |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6489 argument.) We add one to it because line 2 has only one line before |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6490 it, and @code{count-lines} counts only the lines @emph{before} the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6491 current line. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6492 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6493 After @code{count-lines} has done its job, and the message has been |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6494 printed in the echo area, the @code{save-excursion} restores point and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6495 mark to their original positions; and @code{save-restriction} restores |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6496 the original narrowing, if any. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6497 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6498 @node narrow Exercise, , what-line, Narrowing & Widening |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6499 @section Exercise with Narrowing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6501 Write a function that will display the first 60 characters of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6502 current buffer, even if you have narrowed the buffer to its latter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6503 half so that the first line is inaccessible. Restore point, mark, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6504 and narrowing. For this exercise, you need to use |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6505 @code{save-restriction}, @code{widen}, @code{goto-char}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6506 @code{point-min}, @code{buffer-substring}, @code{message}, and other |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6507 functions, a whole potpourri. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6508 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6509 @node car cdr & cons, Cutting & Storing Text, Narrowing & Widening, Top |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6510 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6511 @chapter @code{car}, @code{cdr}, @code{cons}: Fundamental Functions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6512 @findex car, @r{introduced} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6513 @findex cdr, @r{introduced} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6514 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6515 In Lisp, @code{car}, @code{cdr}, and @code{cons} are fundamental |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6516 functions. The @code{cons} function is used to construct lists, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6517 the @code{car} and @code{cdr} functions are used to take them apart. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6518 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6519 In the walk through of the @code{copy-region-as-kill} function, we |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6520 will see @code{cons} as well as two variants on @code{cdr}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6521 namely, @code{setcdr} and @code{nthcdr}. (@xref{copy-region-as-kill}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6522 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6523 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6524 * Strange Names:: An historical aside: why the strange names? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6525 * car & cdr:: Functions for extracting part of a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6526 * cons:: Constructing a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6527 * nthcdr:: Calling @code{cdr} repeatedly. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6528 * nth:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6529 * setcar:: Changing the first element of a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6530 * setcdr:: Changing the rest of a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6531 * cons Exercise:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6532 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6533 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6534 @node Strange Names, car & cdr, car cdr & cons, car cdr & cons |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6535 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6536 @unnumberedsec Strange Names |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6537 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6538 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6539 The name of the @code{cons} function is not unreasonable: it is an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6540 abbreviation of the word `construct'. The origins of the names for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6541 @code{car} and @code{cdr}, on the other hand, are esoteric: @code{car} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6542 is an acronym from the phrase `Contents of the Address part of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6543 Register'; and @code{cdr} (pronounced `could-er') is an acronym from |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6544 the phrase `Contents of the Decrement part of the Register'. These |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6545 phrases refer to specific pieces of hardware on the very early |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6546 computer on which the original Lisp was developed. Besides being |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6547 obsolete, the phrases have been completely irrelevant for more than 25 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6548 years to anyone thinking about Lisp. Nonetheless, although a few |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6549 brave scholars have begun to use more reasonable names for these |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6550 functions, the old terms are still in use. In particular, since the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6551 terms are used in the Emacs Lisp source code, we will use them in this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6552 introduction. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6553 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6554 @node car & cdr, cons, Strange Names, car cdr & cons |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6555 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6556 @section @code{car} and @code{cdr} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6557 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6558 The @sc{car} of a list is, quite simply, the first item in the list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6559 Thus the @sc{car} of the list @code{(rose violet daisy buttercup)} is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6560 @code{rose}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6561 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6562 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6563 If you are reading this in Info in GNU Emacs, you can see this by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6564 evaluating the following: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6565 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6566 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6567 (car '(rose violet daisy buttercup)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6568 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6569 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6570 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6571 After evaluating the expression, @code{rose} will appear in the echo |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6572 area. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6573 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6574 Clearly, a more reasonable name for the @code{car} function would be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6575 @code{first} and this is often suggested. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6576 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6577 @code{car} does not remove the first item from the list; it only reports |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6578 what it is. After @code{car} has been applied to a list, the list is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6579 still the same as it was. In the jargon, @code{car} is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6580 `non-destructive'. This feature turns out to be important. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6581 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6582 The @sc{cdr} of a list is the rest of the list, that is, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6583 @code{cdr} function returns the part of the list that follows the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6584 first item. Thus, while the @sc{car} of the list @code{'(rose violet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6585 daisy buttercup)} is @code{rose}, the rest of the list, the value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6586 returned by the @code{cdr} function, is @code{(violet daisy |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6587 buttercup)}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6588 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6589 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6590 You can see this by evaluating the following in the usual way: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6591 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6592 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6593 (cdr '(rose violet daisy buttercup)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6594 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6595 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6596 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6597 When you evaluate this, @code{(violet daisy buttercup)} will appear in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6598 the echo area. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6599 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6600 Like @code{car}, @code{cdr} does not remove any elements from the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6601 list---it just returns a report of what the second and subsequent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6602 elements are. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6603 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6604 Incidentally, in the example, the list of flowers is quoted. If it were |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6605 not, the Lisp interpreter would try to evaluate the list by calling |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6606 @code{rose} as a function. In this example, we do not want to do that. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6607 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6608 Clearly, a more reasonable name for @code{cdr} would be @code{rest}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6609 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6610 (There is a lesson here: when you name new functions, consider very |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6611 carefully what you are doing, since you may be stuck with the names |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6612 for far longer than you expect. The reason this document perpetuates |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6613 these names is that the Emacs Lisp source code uses them, and if I did |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6614 not use them, you would have a hard time reading the code; but do, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6615 please, try to avoid using these terms yourself. The people who come |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6616 after you will be grateful to you.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6617 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6618 When @code{car} and @code{cdr} are applied to a list made up of symbols, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6619 such as the list @code{(pine fir oak maple)}, the element of the list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6620 returned by the function @code{car} is the symbol @code{pine} without |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6621 any parentheses around it. @code{pine} is the first element in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6622 list. However, the @sc{cdr} of the list is a list itself, @code{(fir |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6623 oak maple)}, as you can see by evaluating the following expressions in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6624 the usual way: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6625 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6626 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6627 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6628 (car '(pine fir oak maple)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6629 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6630 (cdr '(pine fir oak maple)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6631 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6632 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6633 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6634 On the other hand, in a list of lists, the first element is itself a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6635 list. @code{car} returns this first element as a list. For example, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6636 the following list contains three sub-lists, a list of carnivores, a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6637 list of herbivores and a list of sea mammals: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6638 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6639 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6640 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6641 (car '((lion tiger cheetah) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6642 (gazelle antelope zebra) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6643 (whale dolphin seal))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6644 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6645 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6646 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6647 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6648 In this example, the first element or @sc{car} of the list is the list of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6649 carnivores, @code{(lion tiger cheetah)}, and the rest of the list is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6650 @code{((gazelle antelope zebra) (whale dolphin seal))}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6651 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6652 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6653 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6654 (cdr '((lion tiger cheetah) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6655 (gazelle antelope zebra) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6656 (whale dolphin seal))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6657 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6658 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6659 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6660 It is worth saying again that @code{car} and @code{cdr} are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6661 non-destructive---that is, they do not modify or change lists to which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6662 they are applied. This is very important for how they are used. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6663 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6664 Also, in the first chapter, in the discussion about atoms, I said that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6665 in Lisp, ``certain kinds of atom, such as an array, can be separated |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6666 into parts; but the mechanism for doing this is different from the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6667 mechanism for splitting a list. As far as Lisp is concerned, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6668 atoms of a list are unsplittable.'' (@xref{Lisp Atoms}.) The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6669 @code{car} and @code{cdr} functions are used for splitting lists and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6670 are considered fundamental to Lisp. Since they cannot split or gain |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6671 access to the parts of an array, an array is considered an atom. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6672 Conversely, the other fundamental function, @code{cons}, can put |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6673 together or construct a list, but not an array. (Arrays are handled |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6674 by array-specific functions. @xref{Arrays, , Arrays, elisp, The GNU |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6675 Emacs Lisp Reference Manual}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6676 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6677 @node cons, nthcdr, car & cdr, car cdr & cons |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6678 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6679 @section @code{cons} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6680 @findex cons, @r{introduced} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6681 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6682 The @code{cons} function constructs lists; it is the inverse of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6683 @code{car} and @code{cdr}. For example, @code{cons} can be used to make |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6684 a four element list from the three element list, @code{(fir oak maple)}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6685 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6686 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6687 (cons 'pine '(fir oak maple)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6688 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6689 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6690 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6691 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6692 After evaluating this list, you will see |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6693 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6694 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6695 (pine fir oak maple) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6696 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6697 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6698 @noindent |
45663
046819540e6d
Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents:
44899
diff
changeset
|
6699 appear in the echo area. @code{cons} causes the creation of a new |
046819540e6d
Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents:
44899
diff
changeset
|
6700 list in which the element is followed by the elements of the original |
046819540e6d
Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents:
44899
diff
changeset
|
6701 list. |
046819540e6d
Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents:
44899
diff
changeset
|
6702 |
046819540e6d
Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents:
44899
diff
changeset
|
6703 We often say that `@code{cons} puts a new element at the beginning of |
046819540e6d
Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents:
44899
diff
changeset
|
6704 a list; it attaches or pushes elements onto the list', but this |
046819540e6d
Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents:
44899
diff
changeset
|
6705 phrasing can be misleading, since @code{cons} does not change an |
046819540e6d
Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents:
44899
diff
changeset
|
6706 existing list, but creates a new one. |
046819540e6d
Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents:
44899
diff
changeset
|
6707 |
046819540e6d
Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents:
44899
diff
changeset
|
6708 Like @code{car} and @code{cdr}, @code{cons} is non-destructive. |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6709 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6710 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6711 * Build a list:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6712 * length:: How to find the length of a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6713 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6714 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6715 @node Build a list, length, cons, cons |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6716 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6717 @unnumberedsubsec Build a list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6718 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6719 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6720 @code{cons} must have a list to attach to.@footnote{Actually, you can |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6721 @code{cons} an element to an atom to produce a dotted pair. Dotted |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6722 pairs are not discussed here; see @ref{Dotted Pair Notation, , Dotted |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6723 Pair Notation, elisp, The GNU Emacs Lisp Reference Manual}.} You |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6724 cannot start from absolutely nothing. If you are building a list, you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6725 need to provide at least an empty list at the beginning. Here is a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6726 series of @code{cons} expressions that build up a list of flowers. If |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6727 you are reading this in Info in GNU Emacs, you can evaluate each of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6728 the expressions in the usual way; the value is printed in this text |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6729 after @samp{@result{}}, which you may read as `evaluates to'. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6730 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6731 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6732 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6733 (cons 'buttercup ()) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6734 @result{} (buttercup) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6735 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6736 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6737 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6738 (cons 'daisy '(buttercup)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6739 @result{} (daisy buttercup) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6740 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6741 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6742 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6743 (cons 'violet '(daisy buttercup)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6744 @result{} (violet daisy buttercup) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6745 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6746 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6747 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6748 (cons 'rose '(violet daisy buttercup)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6749 @result{} (rose violet daisy buttercup) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6750 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6751 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6752 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6753 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6754 In the first example, the empty list is shown as @code{()} and a list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6755 made up of @code{buttercup} followed by the empty list is constructed. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6756 As you can see, the empty list is not shown in the list that was |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6757 constructed. All that you see is @code{(buttercup)}. The empty list is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6758 not counted as an element of a list because there is nothing in an empty |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6759 list. Generally speaking, an empty list is invisible. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6760 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6761 The second example, @code{(cons 'daisy '(buttercup))} constructs a new, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6762 two element list by putting @code{daisy} in front of @code{buttercup}; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6763 and the third example constructs a three element list by putting |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6764 @code{violet} in front of @code{daisy} and @code{buttercup}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6765 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6766 @node length, , Build a list, cons |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6767 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6768 @subsection Find the Length of a List: @code{length} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6769 @findex length |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6770 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6771 You can find out how many elements there are in a list by using the Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6772 function @code{length}, as in the following examples: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6773 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6774 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6775 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6776 (length '(buttercup)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6777 @result{} 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6778 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6779 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6780 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6781 (length '(daisy buttercup)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6782 @result{} 2 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6783 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6784 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6785 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6786 (length (cons 'violet '(daisy buttercup))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6787 @result{} 3 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6788 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6789 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6790 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6791 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6792 In the third example, the @code{cons} function is used to construct a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6793 three element list which is then passed to the @code{length} function as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6794 its argument. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6795 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6796 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6797 We can also use @code{length} to count the number of elements in an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6798 empty list: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6799 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6800 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6801 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6802 (length ()) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6803 @result{} 0 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6804 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6805 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6806 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6807 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6808 As you would expect, the number of elements in an empty list is zero. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6809 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6810 An interesting experiment is to find out what happens if you try to find |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6811 the length of no list at all; that is, if you try to call @code{length} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6812 without giving it an argument, not even an empty list: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6813 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6814 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6815 (length ) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6816 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6817 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6818 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6819 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6820 What you see, if you evaluate this, is the error message |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6821 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6822 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6823 Wrong number of arguments: #<subr length>, 0 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6824 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6825 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6826 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6827 This means that the function receives the wrong number of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6828 arguments, zero, when it expects some other number of arguments. In |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6829 this case, one argument is expected, the argument being a list whose |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6830 length the function is measuring. (Note that @emph{one} list is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6831 @emph{one} argument, even if the list has many elements inside it.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6832 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6833 The part of the error message that says @samp{#<subr length>} is the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6834 name of the function. This is written with a special notation, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6835 @samp{#<subr}, that indicates that the function @code{length} is one |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6836 of the primitive functions written in C rather than in Emacs Lisp. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6837 (@samp{subr} is an abbreviation for `subroutine'.) @xref{What Is a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6838 Function, , What Is a Function?, elisp , The GNU Emacs Lisp Reference |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6839 Manual}, for more about subroutines. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6840 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6841 @node nthcdr, nth, cons, car cdr & cons |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6842 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6843 @section @code{nthcdr} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6844 @findex nthcdr |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6845 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6846 The @code{nthcdr} function is associated with the @code{cdr} function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6847 What it does is take the @sc{cdr} of a list repeatedly. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6848 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6849 If you take the @sc{cdr} of the list @code{(pine fir |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6850 oak maple)}, you will be returned the list @code{(fir oak maple)}. If you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6851 repeat this on what was returned, you will be returned the list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6852 @code{(oak maple)}. (Of course, repeated @sc{cdr}ing on the original |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6853 list will just give you the original @sc{cdr} since the function does |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6854 not change the list. You need to evaluate the @sc{cdr} of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6855 @sc{cdr} and so on.) If you continue this, eventually you will be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6856 returned an empty list, which in this case, instead of being shown as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6857 @code{()} is shown as @code{nil}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6858 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6859 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6860 For review, here is a series of repeated @sc{cdr}s, the text following |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6861 the @samp{@result{}} shows what is returned. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6862 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6863 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6864 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6865 (cdr '(pine fir oak maple)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6866 @result{}(fir oak maple) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6867 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6868 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6869 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6870 (cdr '(fir oak maple)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6871 @result{} (oak maple) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6872 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6873 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6874 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6875 (cdr '(oak maple)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6876 @result{}(maple) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6877 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6878 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6879 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6880 (cdr '(maple)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6881 @result{} nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6882 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6883 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6884 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6885 (cdr 'nil) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6886 @result{} nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6887 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6888 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6889 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6890 (cdr ()) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6891 @result{} nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6892 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6893 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6894 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6895 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6896 You can also do several @sc{cdr}s without printing the values in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6897 between, like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6898 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6899 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6900 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6901 (cdr (cdr '(pine fir oak maple))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6902 @result{} (oak maple) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6903 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6904 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6905 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6906 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6907 In this example, the Lisp interpreter evaluates the innermost list first. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6908 The innermost list is quoted, so it just passes the list as it is to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6909 innermost @code{cdr}. This @code{cdr} passes a list made up of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6910 second and subsequent elements of the list to the outermost @code{cdr}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6911 which produces a list composed of the third and subsequent elements of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6912 the original list. In this example, the @code{cdr} function is repeated |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6913 and returns a list that consists of the original list without its |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6914 first two elements. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6915 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6916 The @code{nthcdr} function does the same as repeating the call to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6917 @code{cdr}. In the following example, the argument 2 is passed to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6918 function @code{nthcdr}, along with the list, and the value returned is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6919 the list without its first two items, which is exactly the same |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6920 as repeating @code{cdr} twice on the list: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6921 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6922 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6923 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6924 (nthcdr 2 '(pine fir oak maple)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6925 @result{} (oak maple) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6926 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6927 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6928 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6929 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6930 Using the original four element list, we can see what happens when |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6931 various numeric arguments are passed to @code{nthcdr}, including 0, 1, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6932 and 5: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6933 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6934 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6935 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6936 ;; @r{Leave the list as it was.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6937 (nthcdr 0 '(pine fir oak maple)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6938 @result{} (pine fir oak maple) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6939 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6940 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6941 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6942 ;; @r{Return a copy without the first element.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6943 (nthcdr 1 '(pine fir oak maple)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6944 @result{} (fir oak maple) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6945 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6946 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6947 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6948 ;; @r{Return a copy of the list without three elements.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6949 (nthcdr 3 '(pine fir oak maple)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6950 @result{} (maple) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6951 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6952 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6953 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6954 ;; @r{Return a copy lacking all four elements.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6955 (nthcdr 4 '(pine fir oak maple)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6956 @result{} nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6957 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6958 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6959 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6960 ;; @r{Return a copy lacking all elements.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6961 (nthcdr 5 '(pine fir oak maple)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6962 @result{} nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6963 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6964 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6965 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6966 @node nth, setcar, nthcdr, car cdr & cons |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6967 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6968 @section @code{nth} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6969 @findex nth |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6970 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6971 The @code{nthcdr} function takes the @sc{cdr} of a list repeatedly. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6972 The @code{nth} function takes the @sc{car} of the result returned by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6973 @code{nthcdr}. It returns the Nth element of the list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6974 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6975 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6976 Thus, if it were not defined in C for speed, the definition of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6977 @code{nth} would be: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6978 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6979 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6980 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6981 (defun nth (n list) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6982 "Returns the Nth element of LIST. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6983 N counts from zero. If LIST is not that long, nil is returned." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6984 (car (nthcdr n list))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6985 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6986 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6987 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6988 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6989 (Originally, @code{nth} was defined in Emacs Lisp in @file{subr.el}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6990 but its definition was redone in C in the 1980s.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6991 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6992 The @code{nth} function returns a single element of a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6993 This can be very convenient. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6994 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6995 Note that the elements are numbered from zero, not one. That is to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6996 say, the first element of a list, its @sc{car} is the zeroth element. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6997 This is called `zero-based' counting and often bothers people who |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6998 are accustomed to the first element in a list being number one, which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
6999 is `one-based'. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7000 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7001 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7002 For example: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7003 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7004 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7005 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7006 (nth 0 '("one" "two" "three")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7007 @result{} "one" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7008 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7009 (nth 1 '("one" "two" "three")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7010 @result{} "two" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7011 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7012 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7013 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7014 It is worth mentioning that @code{nth}, like @code{nthcdr} and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7015 @code{cdr}, does not change the original list---the function is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7016 non-destructive. This is in sharp contrast to the @code{setcar} and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7017 @code{setcdr} functions. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7018 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7019 @node setcar, setcdr, nth, car cdr & cons |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7020 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7021 @section @code{setcar} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7022 @findex setcar |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7023 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7024 As you might guess from their names, the @code{setcar} and @code{setcdr} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7025 functions set the @sc{car} or the @sc{cdr} of a list to a new value. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7026 They actually change the original list, unlike @code{car} and @code{cdr} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7027 which leave the original list as it was. One way to find out how this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7028 works is to experiment. We will start with the @code{setcar} function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7029 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7030 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7031 First, we can make a list and then set the value of a variable to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7032 list, using the @code{setq} function. Here is a list of animals: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7033 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7034 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7035 (setq animals '(antelope giraffe lion tiger)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7036 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7037 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7038 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7039 If you are reading this in Info inside of GNU Emacs, you can evaluate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7040 this expression in the usual fashion, by positioning the cursor after |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7041 the expression and typing @kbd{C-x C-e}. (I'm doing this right here as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7042 I write this. This is one of the advantages of having the interpreter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7043 built into the computing environment.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7044 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7045 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7046 When we evaluate the variable @code{animals}, we see that it is bound to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7047 the list @code{(antelope giraffe lion tiger)}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7048 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7049 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7050 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7051 animals |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7052 @result{} (antelope giraffe lion tiger) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7053 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7054 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7055 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7056 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7057 Put another way, the variable @code{animals} points to the list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7058 @code{(antelope giraffe lion tiger)}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7059 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7060 Next, evaluate the function @code{setcar} while passing it two |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7061 arguments, the variable @code{animals} and the quoted symbol |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7062 @code{hippopotamus}; this is done by writing the three element list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7063 @code{(setcar animals 'hippopotamus)} and then evaluating it in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7064 usual fashion: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7065 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7066 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7067 (setcar animals 'hippopotamus) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7068 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7069 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7070 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7071 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7072 After evaluating this expression, evaluate the variable @code{animals} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7073 again. You will see that the list of animals has changed: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7074 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7075 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7076 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7077 animals |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7078 @result{} (hippopotamus giraffe lion tiger) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7079 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7080 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7081 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7082 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7083 The first element on the list, @code{antelope} is replaced by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7084 @code{hippopotamus}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7085 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7086 So we can see that @code{setcar} did not add a new element to the list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7087 as @code{cons} would have; it replaced @code{giraffe} with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7088 @code{hippopotamus}; it @emph{changed} the list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7089 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7090 @node setcdr, cons Exercise, setcar, car cdr & cons |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7091 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7092 @section @code{setcdr} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7093 @findex setcdr |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7094 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7095 The @code{setcdr} function is similar to the @code{setcar} function, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7096 except that the function replaces the second and subsequent elements of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7097 a list rather than the first element. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7098 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7099 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7100 To see how this works, set the value of the variable to a list of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7101 domesticated animals by evaluating the following expression: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7102 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7103 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7104 (setq domesticated-animals '(horse cow sheep goat)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7105 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7106 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7107 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7108 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7109 If you now evaluate the list, you will be returned the list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7110 @code{(horse cow sheep goat)}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7111 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7112 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7113 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7114 domesticated-animals |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7115 @result{} (horse cow sheep goat) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7116 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7117 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7118 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7119 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7120 Next, evaluate @code{setcdr} with two arguments, the name of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7121 variable which has a list as its value, and the list to which the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7122 @sc{cdr} of the first list will be set; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7123 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7124 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7125 (setcdr domesticated-animals '(cat dog)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7126 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7127 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7128 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7129 If you evaluate this expression, the list @code{(cat dog)} will appear |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7130 in the echo area. This is the value returned by the function. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7131 result we are interested in is the ``side effect'', which we can see by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7132 evaluating the variable @code{domesticated-animals}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7133 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7134 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7135 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7136 domesticated-animals |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7137 @result{} (horse cat dog) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7138 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7139 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7140 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7141 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7142 Indeed, the list is changed from @code{(horse cow sheep goat)} to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7143 @code{(horse cat dog)}. The @sc{cdr} of the list is changed from |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7144 @code{(cow sheep goat)} to @code{(cat dog)}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7145 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7146 @node cons Exercise, , setcdr, car cdr & cons |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7147 @section Exercise |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7148 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7149 Construct a list of four birds by evaluating several expressions with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7150 @code{cons}. Find out what happens when you @code{cons} a list onto |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7151 itself. Replace the first element of the list of four birds with a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7152 fish. Replace the rest of that list with a list of other fish. |
44899
ebddb2618c17
Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents:
43431
diff
changeset
|
7153 |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7154 @node Cutting & Storing Text, List Implementation, car cdr & cons, Top |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7155 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7156 @chapter Cutting and Storing Text |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7157 @cindex Cutting and storing text |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7158 @cindex Storing and cutting text |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7159 @cindex Killing text |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7160 @cindex Clipping text |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7161 @cindex Erasing text |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7162 @cindex Deleting text |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7163 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7164 Whenever you cut or clip text out of a buffer with a `kill' command in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7165 GNU Emacs, it is stored in a list and you can bring it back with a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7166 `yank' command. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7167 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7168 (The use of the word `kill' in Emacs for processes which specifically |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7169 @emph{do not} destroy the values of the entities is an unfortunate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7170 historical accident. A much more appropriate word would be `clip' since |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7171 that is what the kill commands do; they clip text out of a buffer and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7172 put it into storage from which it can be brought back. I have often |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7173 been tempted to replace globally all occurrences of `kill' in the Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7174 sources with `clip' and all occurrences of `killed' with `clipped'.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7175 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7176 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7177 * Storing Text:: Text is stored in a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7178 * zap-to-char:: Cutting out text up to a character. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7179 * kill-region:: Cutting text out of a region. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7180 * Digression into C:: Minor note on C programming language macros. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7181 * defvar:: How to give a variable an initial value. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7182 * copy-region-as-kill:: A definition for copying text. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7183 * cons & search-fwd Review:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7184 * search Exercises:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7185 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7186 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7187 @node Storing Text, zap-to-char, Cutting & Storing Text, Cutting & Storing Text |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7188 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7189 @unnumberedsec Storing Text in a List |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7190 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7191 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7192 When text is cut out of a buffer, it is stored on a list. Successive |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7193 pieces of text are stored on the list successively, so the list might |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7194 look like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7195 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7196 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7197 ("a piece of text" "previous piece") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7198 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7199 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7200 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7201 @noindent |
45663
046819540e6d
Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents:
44899
diff
changeset
|
7202 The function @code{cons} can be used to to create a new list from a |
046819540e6d
Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents:
44899
diff
changeset
|
7203 piece of text (an `atom', to use the jargon) and an existing list, |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7204 like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7205 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7206 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7207 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7208 (cons "another piece" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7209 '("a piece of text" "previous piece")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7210 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7211 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7212 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7213 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7214 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7215 If you evaluate this expression, a list of three elements will appear in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7216 the echo area: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7217 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7218 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7219 ("another piece" "a piece of text" "previous piece") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7220 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7221 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7222 With the @code{car} and @code{nthcdr} functions, you can retrieve |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7223 whichever piece of text you want. For example, in the following code, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7224 @code{nthcdr 1 @dots{}} returns the list with the first item removed; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7225 and the @code{car} returns the first element of that remainder---the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7226 second element of the original list: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7227 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7228 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7229 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7230 (car (nthcdr 1 '("another piece" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7231 "a piece of text" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7232 "previous piece"))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7233 @result{} "a piece of text" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7234 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7235 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7236 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7237 The actual functions in Emacs are more complex than this, of course. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7238 The code for cutting and retrieving text has to be written so that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7239 Emacs can figure out which element in the list you want---the first, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7240 second, third, or whatever. In addition, when you get to the end of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7241 the list, Emacs should give you the first element of the list, rather |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7242 than nothing at all. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7243 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7244 The list that holds the pieces of text is called the @dfn{kill ring}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7245 This chapter leads up to a description of the kill ring and how it is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7246 used by first tracing how the @code{zap-to-char} function works. This |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7247 function uses (or `calls') a function that invokes a function that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7248 manipulates the kill ring. Thus, before reaching the mountains, we |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7249 climb the foothills. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7251 A subsequent chapter describes how text that is cut from the buffer is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7252 retrieved. @xref{Yanking, , Yanking Text Back}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7253 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7254 @node zap-to-char, kill-region, Storing Text, Cutting & Storing Text |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7255 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7256 @section @code{zap-to-char} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7257 @findex zap-to-char |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7258 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7259 The @code{zap-to-char} function barely changed between GNU Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7260 version 19 and GNU Emacs version 21. However, @code{zap-to-char} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7261 calls another function, @code{kill-region}, which enjoyed a major rewrite |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7262 on the way to version 21. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7263 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7264 The @code{kill-region} function in Emacs 19 is complex, but does not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7265 use code that is important at this time. We will skip it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7266 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7267 The @code{kill-region} function in Emacs 21 is easier to read than the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7268 same function in Emacs 19 and introduces a very important concept, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7269 that of error handling. We will walk through the function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7270 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7271 But first, let us look at the interactive @code{zap-to-char} function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7272 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7273 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7274 * Complete zap-to-char:: The complete implementation. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7275 * zap-to-char interactive:: A three part interactive expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7276 * zap-to-char body:: A short overview. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7277 * search-forward:: How to search for a string. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7278 * progn:: The @code{progn} special form. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7279 * Summing up zap-to-char:: Using @code{point} and @code{search-forward}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7280 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7281 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7282 @node Complete zap-to-char, zap-to-char interactive, zap-to-char, zap-to-char |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7283 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7284 @unnumberedsubsec The Complete @code{zap-to-char} Implementation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7285 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7286 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7287 The GNU Emacs version 19 and version 21 implementations of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7288 @code{zap-to-char} function are nearly identical in form, and they |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7289 work alike. The function removes the text in the region between the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7290 location of the cursor (i.e., of point) up to and including the next |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7291 occurrence of a specified character. The text that @code{zap-to-char} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7292 removes is put in the kill ring; and it can be retrieved from the kill |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7293 ring by typing @kbd{C-y} (@code{yank}). If the command is given an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7294 argument, it removes text through that number of occurrences. Thus, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7295 if the cursor were at the beginning of this sentence and the character |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7296 were @samp{s}, @samp{Thus} would be removed. If the argument were |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7297 two, @samp{Thus, if the curs} would be removed, up to and including |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7298 the @samp{s} in @samp{cursor}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7299 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7300 If the specified character is not found, @code{zap-to-char} will say |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7301 ``Search failed'', tell you the character you typed, and not remove |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7302 any text. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7303 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7304 In order to determine how much text to remove, @code{zap-to-char} uses |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7305 a search function. Searches are used extensively in code that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7306 manipulates text, and we will focus attention on them as well as on the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7307 deletion command. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7308 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7309 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7310 Here is the complete text of the version 19 implementation of the function: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7311 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7312 @c v 19 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7313 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7314 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7315 (defun zap-to-char (arg char) ; version 19 implementation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7316 "Kill up to and including ARG'th occurrence of CHAR. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7317 Goes backward if ARG is negative; error if CHAR not found." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7318 (interactive "*p\ncZap to char: ") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7319 (kill-region (point) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7320 (progn |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7321 (search-forward |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7322 (char-to-string char) nil nil arg) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7323 (point)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7324 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7325 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7326 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7327 @node zap-to-char interactive, zap-to-char body, Complete zap-to-char, zap-to-char |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7328 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7329 @subsection The @code{interactive} Expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7330 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7331 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7332 The interactive expression in the @code{zap-to-char} command looks like |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7333 this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7334 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7335 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7336 (interactive "*p\ncZap to char: ") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7337 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7338 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7339 The part within quotation marks, @code{"*p\ncZap to char:@: "}, specifies |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7340 three different things. First, and most simply, the asterisk, @samp{*}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7341 causes an error to be signalled if the buffer is read-only. This means that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7342 if you try @code{zap-to-char} in a read-only buffer you will not be able to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7343 remove text, and you will receive a message that says ``Buffer is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7344 read-only''; your terminal may beep at you as well. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7345 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7346 The version 21 implementation does not have the asterisk, @samp{*}. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7347 function works the same as in version 19: in both cases, it cannot |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7348 remove text from a read-only buffer but the function does copy the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7349 text that would have been removed to the kill ring. Also, in both |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7350 cases, you see an error message. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7351 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7352 However, the version 19 implementation copies text from a read-only |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7353 buffer only because of a mistake in the implementation of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7354 @code{interactive}. According to the documentation for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7355 @code{interactive}, the asterisk, @samp{*}, should prevent the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7356 @code{zap-to-char} function from doing anything at all when the buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7357 is read only. The function should not copy the text to the kill ring. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7358 It is a bug that it does. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7359 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7360 In version 21, @code{interactive} is implemented correctly. So the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7361 asterisk, @samp{*}, had to be removed from the interactive |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7362 specification. If you insert an @samp{*} and evaluate the function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7363 definition, then the next time you run the @code{zap-to-char} function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7364 on a read-only buffer, you will not copy any text. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7365 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7366 That change aside, and a change to the documentation, the two versions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7367 of the @code{zap-to-char} function are identical. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7368 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7369 Let us continue with the interactive specification. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7370 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7371 The second part of @code{"*p\ncZap to char:@: "} is the @samp{p}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7372 This part is separated from the next part by a newline, @samp{\n}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7373 The @samp{p} means that the first argument to the function will be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7374 passed the value of a `processed prefix'. The prefix argument is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7375 passed by typing @kbd{C-u} and a number, or @kbd{M-} and a number. If |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7376 the function is called interactively without a prefix, 1 is passed to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7377 this argument. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7378 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7379 The third part of @code{"*p\ncZap to char:@: "} is @samp{cZap to char:@: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7380 }. In this part, the lower case @samp{c} indicates that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7381 @code{interactive} expects a prompt and that the argument will be a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7382 character. The prompt follows the @samp{c} and is the string @samp{Zap |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7383 to char:@: } (with a space after the colon to make it look good). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7384 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7385 What all this does is prepare the arguments to @code{zap-to-char} so they |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7386 are of the right type, and give the user a prompt. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7387 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7388 @node zap-to-char body, search-forward, zap-to-char interactive, zap-to-char |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7389 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7390 @subsection The Body of @code{zap-to-char} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7391 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7392 The body of the @code{zap-to-char} function contains the code that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7393 kills (that is, removes) the text in the region from the current |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7394 position of the cursor up to and including the specified character. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7395 The first part of the code looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7396 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7397 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7398 (kill-region (point) @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7399 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7400 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7401 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7402 @code{(point)} is the current position of the cursor. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7403 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7404 The next part of the code is an expression using @code{progn}. The body |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7405 of the @code{progn} consists of calls to @code{search-forward} and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7406 @code{point}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7407 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7408 It is easier to understand how @code{progn} works after learning about |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7409 @code{search-forward}, so we will look at @code{search-forward} and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7410 then at @code{progn}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7411 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7412 @node search-forward, progn, zap-to-char body, zap-to-char |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7413 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7414 @subsection The @code{search-forward} Function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7415 @findex search-forward |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7416 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7417 The @code{search-forward} function is used to locate the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7418 zapped-for-character in @code{zap-to-char}. If the search is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7419 successful, @code{search-forward} leaves point immediately after the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7420 last character in the target string. (In @code{zap-to-char}, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7421 target string is just one character long.) If the search is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7422 backwards, @code{search-forward} leaves point just before the first |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7423 character in the target. Also, @code{search-forward} returns @code{t} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7424 for true. (Moving point is therefore a `side effect'.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7425 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7426 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7427 In @code{zap-to-char}, the @code{search-forward} function looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7428 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7429 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7430 (search-forward (char-to-string char) nil nil arg) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7431 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7432 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7433 The @code{search-forward} function takes four arguments: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7434 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7435 @enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7436 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7437 The first argument is the target, what is searched for. This must be a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7438 string, such as @samp{"z"}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7439 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7440 As it happens, the argument passed to @code{zap-to-char} is a single |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7441 character. Because of the way computers are built, the Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7442 interpreter may treat a single character as being different from a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7443 string of characters. Inside the computer, a single character has a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7444 different electronic format than a string of one character. (A single |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7445 character can often be recorded in the computer using exactly one |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7446 byte; but a string may be longer, and the computer needs to be ready |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7447 for this.) Since the @code{search-forward} function searches for a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7448 string, the character that the @code{zap-to-char} function receives as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7449 its argument must be converted inside the computer from one format to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7450 the other; otherwise the @code{search-forward} function will fail. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7451 The @code{char-to-string} function is used to make this conversion. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7452 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7453 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7454 The second argument bounds the search; it is specified as a position in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7455 the buffer. In this case, the search can go to the end of the buffer, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7456 so no bound is set and the second argument is @code{nil}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7457 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7458 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7459 The third argument tells the function what it should do if the search |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7460 fails---it can signal an error (and print a message) or it can return |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7461 @code{nil}. A @code{nil} as the third argument causes the function to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7462 signal an error when the search fails. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7463 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7464 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7465 The fourth argument to @code{search-forward} is the repeat count---how |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7466 many occurrences of the string to look for. This argument is optional |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7467 and if the function is called without a repeat count, this argument is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7468 passed the value 1. If this argument is negative, the search goes |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7469 backwards. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7470 @end enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7471 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7472 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7473 In template form, a @code{search-forward} expression looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7474 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7475 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7476 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7477 (search-forward "@var{target-string}" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7478 @var{limit-of-search} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7479 @var{what-to-do-if-search-fails} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7480 @var{repeat-count}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7481 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7482 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7483 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7484 We will look at @code{progn} next. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7485 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7486 @node progn, Summing up zap-to-char, search-forward, zap-to-char |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7487 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7488 @subsection The @code{progn} Special Form |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7489 @findex progn |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7490 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7491 @code{progn} is a special form that causes each of its arguments to be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7492 evaluated in sequence and then returns the value of the last one. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7493 preceding expressions are evaluated only for the side effects they |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7494 perform. The values produced by them are discarded. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7495 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7496 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7497 The template for a @code{progn} expression is very simple: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7498 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7499 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7500 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7501 (progn |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7502 @var{body}@dots{}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7503 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7504 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7505 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7506 In @code{zap-to-char}, the @code{progn} expression has to do two things: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7507 put point in exactly the right position; and return the location of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7508 point so that @code{kill-region} will know how far to kill to. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7509 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7510 The first argument to the @code{progn} is @code{search-forward}. When |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7511 @code{search-forward} finds the string, the function leaves point |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7512 immediately after the last character in the target string. (In this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7513 case the target string is just one character long.) If the search is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7514 backwards, @code{search-forward} leaves point just before the first |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7515 character in the target. The movement of point is a side effect. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7516 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7517 The second and last argument to @code{progn} is the expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7518 @code{(point)}. This expression returns the value of point, which in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7519 this case will be the location to which it has been moved by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7520 @code{search-forward}. This value is returned by the @code{progn} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7521 expression and is passed to @code{kill-region} as @code{kill-region}'s |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7522 second argument. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7523 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7524 @node Summing up zap-to-char, , progn, zap-to-char |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7525 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7526 @subsection Summing up @code{zap-to-char} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7527 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7528 Now that we have seen how @code{search-forward} and @code{progn} work, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7529 we can see how the @code{zap-to-char} function works as a whole. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7530 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7531 The first argument to @code{kill-region} is the position of the cursor |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7532 when the @code{zap-to-char} command is given---the value of point at |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7533 that time. Within the @code{progn}, the search function then moves |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7534 point to just after the zapped-to-character and @code{point} returns the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7535 value of this location. The @code{kill-region} function puts together |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7536 these two values of point, the first one as the beginning of the region |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7537 and the second one as the end of the region, and removes the region. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7538 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7539 The @code{progn} special form is necessary because the @code{kill-region} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7540 command takes two arguments; and it would fail if @code{search-forward} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7541 and @code{point} expressions were written in sequence as two |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7542 additional arguments. The @code{progn} expression is a single argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7543 to @code{kill-region} and returns the one value that @code{kill-region} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7544 needs for its second argument. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7545 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7546 @node kill-region, Digression into C, zap-to-char, Cutting & Storing Text |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7547 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7548 @section @code{kill-region} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7549 @findex kill-region |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7550 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7551 The @code{zap-to-char} function uses the @code{kill-region} function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7552 This function clips text from a region and copies that text to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7553 the kill ring, from which it may be retrieved. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7554 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7555 The Emacs 21 version of that function uses @code{condition-case} and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7556 @code{copy-region-as-kill}, both of which we will explain. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7557 @code{condition-case} is an important special form. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7558 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7559 In essence, the @code{kill-region} function calls |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7560 @code{condition-case}, which takes three arguments. In this function, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7561 the first argument does nothing. The second argument contains the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7562 code that does the work when all goes well. The third argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7563 contains the code that is called in the event of an error. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7564 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7565 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7566 * Complete kill-region:: The function definition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7567 * condition-case:: Dealing with a problem. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7568 * delete-and-extract-region:: Doing the work. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7569 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7570 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7571 @node Complete kill-region, condition-case, kill-region, kill-region |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7572 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7573 @unnumberedsubsec The Complete @code{kill-region} Definition |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7574 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7575 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7576 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7577 We will go through the @code{condition-case} code in a moment. First, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7578 let us look at the complete definition of @code{kill-region}, with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7579 comments added: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7580 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7581 @c v 21 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7582 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7583 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7584 (defun kill-region (beg end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7585 "Kill between point and mark. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7586 The text is deleted but saved in the kill ring." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7587 (interactive "r") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7588 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7589 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7590 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7591 ;; 1. `condition-case' takes three arguments. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7592 ;; If the first argument is nil, as it is here, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7593 ;; information about the error signal is not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7594 ;; stored for use by another function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7595 (condition-case nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7596 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7597 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7598 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7599 ;; 2. The second argument to `condition-case' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7600 ;; tells the Lisp interpreter what to do when all goes well. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7601 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7602 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7603 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7604 ;; The `delete-and-extract-region' function usually does the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7605 ;; work. If the beginning and ending of the region are both |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7606 ;; the same, then the variable `string' will be empty, or nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7607 (let ((string (delete-and-extract-region beg end))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7608 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7609 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7610 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7611 ;; `when' is an `if' clause that cannot take an `else-part'. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7612 ;; Emacs normally sets the value of `last-command' to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7613 ;; previous command. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7614 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7615 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7616 ;; `kill-append' concatenates the new string and the old. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7617 ;; `kill-new' inserts text into a new item in the kill ring. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7618 (when string |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7619 (if (eq last-command 'kill-region) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7620 ;; if true, prepend string |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7621 (kill-append string (< end beg)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7622 (kill-new string))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7623 (setq this-command 'kill-region)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7624 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7625 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7626 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7627 ;; 3. The third argument to `condition-case' tells the interpreter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7628 ;; what to do with an error. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7629 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7630 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7631 ;; The third argument has a conditions part and a body part. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7632 ;; If the conditions are met (in this case, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7633 ;; if text or buffer is read-only) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7634 ;; then the body is executed. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7635 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7636 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7637 ((buffer-read-only text-read-only) ;; this is the if-part |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7638 ;; then... |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7639 (copy-region-as-kill beg end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7640 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7641 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7642 (if kill-read-only-ok ;; usually this variable is nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7643 (message "Read only text copied to kill ring") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7644 ;; or else, signal an error if the buffer is read-only; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7645 (barf-if-buffer-read-only) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7646 ;; and, in any case, signal that the text is read-only. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7647 (signal 'text-read-only (list (current-buffer))))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7648 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7649 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7650 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7651 @node condition-case, delete-and-extract-region, Complete kill-region, kill-region |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7652 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7653 @subsection @code{condition-case} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7654 @findex condition-case |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7655 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7656 As we have seen earlier (@pxref{Making Errors, , Generate an Error |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7657 Message}), when the Emacs Lisp interpreter has trouble evaluating an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7658 expression, it provides you with help; in the jargon, this is called |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7659 ``signaling an error''. Usually, the computer stops the program and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7660 shows you a message. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7661 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7662 However, some programs undertake complicated actions. They should not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7663 simply stop on an error. In the @code{kill-region} function, the most |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7664 likely error is that you will try to kill text that is read-only and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7665 cannot be removed. So the @code{kill-region} function contains code |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7666 to handle this circumstance. This code, which makes up the body of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7667 the @code{kill-region} function, is inside of a @code{condition-case} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7668 special form. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7669 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7670 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7671 The template for @code{condition-case} looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7672 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7673 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7674 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7675 (condition-case |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7676 @var{var} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7677 @var{bodyform} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7678 @var{error-handler}@dots{}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7679 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7680 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7681 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7682 The second argument, @var{bodyform}, is straightforward. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7683 @code{condition-case} special form causes the Lisp interpreter to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7684 evaluate the code in @var{bodyform}. If no error occurs, the special |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7685 form returns the code's value and produces the side-effects, if any. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7686 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7687 In short, the @var{bodyform} part of a @code{condition-case} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7688 expression determines what should happen when everything works |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7689 correctly. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7690 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7691 However, if an error occurs, among its other actions, the function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7692 generating the error signal will define one or more error condition |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7693 names. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7694 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7695 An error handler is the third argument to @code{condition case}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7696 An error handler has two parts, a @var{condition-name} and a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7697 @var{body}. If the @var{condition-name} part of an error handler |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7698 matches a condition name generated by an error, then the @var{body} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7699 part of the error handler is run. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7700 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7701 As you will expect, the @var{condition-name} part of an error handler |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7702 may be either a single condition name or a list of condition names. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7703 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7704 Also, a complete @code{condition-case} expression may contain more |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7705 than one error handler. When an error occurs, the first applicable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7706 handler is run. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7707 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7708 Lastly, the first argument to the @code{condition-case} expression, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7709 the @var{var} argument, is sometimes bound to a variable that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7710 contains information about the error. However, if that argument is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7711 nil, as is the case in @code{kill-region}, that information is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7712 discarded. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7713 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7714 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7715 In brief, in the @code{kill-region} function, the code |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7716 @code{condition-case} works like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7717 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7718 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7719 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7720 @var{If no errors}, @var{run only this code} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7721 @var{but}, @var{if errors}, @var{run this other code}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7722 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7723 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7724 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7725 @node delete-and-extract-region, , condition-case, kill-region |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7726 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7727 @subsection @code{delete-and-extract-region} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7728 @findex delete-and-extract-region |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7729 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7730 A @code{condition-case} expression has two parts, a part that is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7731 evaluated in the expectation that all will go well, but which may |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7732 generate an error; and a part that is evaluated when there is an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7733 error. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7734 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7735 First, let us look at the code in @code{kill-region} that is run in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7736 the expectation that all goes well. This is the core of the function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7737 The code looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7738 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7739 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7740 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7741 (let ((string (delete-and-extract-region beg end))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7742 (when string |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7743 (if (eq last-command 'kill-region) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7744 (kill-append string (< end beg)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7745 (kill-new string))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7746 (setq this-command 'kill-region)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7747 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7748 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7749 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7750 It looks complicated because we have the new functions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7751 @code{delete-and-extract-region}, @code{kill-append}, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7752 @code{kill-new} as well as the new variables, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7753 @code{last-command} and @code{this-command}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7754 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7755 The @code{delete-and-extract-region} function is straightforward. It |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7756 is a built-in function that deletes the text in a region (a side |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7757 effect) and also returns that text. This is the function that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7758 actually removes the text. (And if it cannot do that, it signals the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7759 error.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7760 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7761 In this @code{let} expression, the text that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7762 @code{delete-and-extract-region} returns is placed in the local |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7763 variable called @samp{string}. This is the text that is removed from |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7764 the buffer. (To be more precise, the variable is set to point to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7765 address of the extracted text; to say it is `placed in' the variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7766 is simply a shorthand.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7767 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7768 If the variable @samp{string} does point to text, that text is added |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7769 to the kill ring. The variable will have a @code{nil} value if no |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7770 text was removed. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7771 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7772 The code uses @code{when} to determine whether the variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7773 @samp{string} points to text. A @code{when} statement is simply a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7774 programmers' convenience. A @code{when} statement is an @code{if} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7775 statement without the possibility of an else clause. In your mind, you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7776 can replace @code{when} with @code{if} and understand what goes on. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7777 That is what the Lisp interpreter does. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7778 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7779 @cindex Macro, lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7780 @cindex Lisp macro |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7781 Technically speaking, @code{when} is a Lisp macro. A Lisp @dfn{macro} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7782 enables you to define new control constructs and other language |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7783 features. It tells the interpreter how to compute another Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7784 expression which will in turn compute the value. In this case, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7785 `other expression' is an @code{if} expression. For more about Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7786 macros, see @ref{Macros, , Macros, elisp, The GNU Emacs Lisp Reference |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7787 Manual}. The C programming language also provides macros. These are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7788 different, but also useful. We will briefly look at C macros in |
45663
046819540e6d
Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents:
44899
diff
changeset
|
7789 @ref{Digression into C}. |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7790 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7791 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7792 If the string has content, then another conditional expression is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7793 executed. This is an @code{if} with both a then-part and an else-part. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7794 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7795 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7796 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7797 (if (eq last-command 'kill-region) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7798 (kill-append string (< end beg)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7799 (kill-new string))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7800 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7801 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7802 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7803 The then-part is evaluated if the previous command was another call to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7804 @code{kill-region}; if not, the else-part is evaluated. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7805 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7806 @code{last-command} is a variable that comes with Emacs that we have |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7807 not seen before. Normally, whenever a function is executed, Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7808 sets the value of @code{last-command} to the previous command. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7809 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7810 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7811 In this segment of the definition, the @code{if} expression checks |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7812 whether the previous command was @code{kill-region}. If it was, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7813 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7814 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7815 (kill-append string (< end beg)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7816 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7817 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7818 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7819 concatenates a copy of the newly clipped text to the just previously |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7820 clipped text in the kill ring. (If the @w{@code{(< end beg))}} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7821 expression is true, @code{kill-append} prepends the string to the just |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7822 previously clipped text. For a detailed discussion, see |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7823 @ref{kill-append function, , The @code{kill-append} function}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7824 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7825 If you then yank back the text, i.e., `paste' it, you get both |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7826 pieces of text at once. That way, if you delete two words in a row, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7827 and then yank them back, you get both words, in their proper order, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7828 with one yank. (The @w{@code{(< end beg))}} expression makes sure the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7829 order is correct.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7830 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7831 On the other hand, if the previous command is not @code{kill-region}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7832 then the @code{kill-new} function is called, which adds the text to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7833 the kill ring as the latest item, and sets the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7834 @code{kill-ring-yank-pointer} variable to point to it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7835 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7836 @node Digression into C, defvar, kill-region, Cutting & Storing Text |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7837 @comment node-name, next, previous, up |
45663
046819540e6d
Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents:
44899
diff
changeset
|
7838 @section Digression into C |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7839 @findex delete-and-extract-region |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7840 @cindex C, a digression into |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7841 @cindex Digression into C |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7842 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7843 The @code{zap-to-char} command uses the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7844 @code{delete-and-extract-region} function, which in turn uses two |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7845 other functions, @code{copy-region-as-kill} and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7846 @code{del_range_1}. The @code{copy-region-as-kill} function will be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7847 described in a following section; it puts a copy of the region in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7848 kill ring so it can be yanked back. (@xref{copy-region-as-kill, , |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7849 @code{copy-region-as-kill}}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7850 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7851 The @code{delete-and-extract-region} function removes the contents of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7852 a region and you cannot get them back. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7853 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7854 Unlike the other code discussed here, @code{delete-and-extract-region} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7855 is not written in Emacs Lisp; it is written in C and is one of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7856 primitives of the GNU Emacs system. Since it is very simple, I will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7857 digress briefly from Lisp and describe it here. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7858 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7859 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7860 Like many of the other Emacs primitives, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7861 @code{delete-and-extract-region} is written as an instance of a C |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7862 macro, a macro being a template for code. The complete macro looks |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7863 like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7864 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7865 @c /usr/local/src/emacs/src/editfns.c |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7866 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7867 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7868 DEFUN ("delete-and-extract-region", Fdelete_and_extract_region, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7869 Sdelete_and_extract_region, 2, 2, 0, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7870 "Delete the text between START and END and return it.") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7871 (start, end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7872 Lisp_Object start, end; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7873 @{ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7874 validate_region (&start, &end); |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7875 return del_range_1 (XINT (start), XINT (end), 1, 1); |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7876 @} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7877 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7878 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7879 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7880 Without going into the details of the macro writing process, let me |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7881 point out that this macro starts with the word @code{DEFUN}. The word |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7882 @code{DEFUN} was chosen since the code serves the same purpose as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7883 @code{defun} does in Lisp. The word @code{DEFUN} is followed by seven |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7884 parts inside of parentheses: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7885 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7886 @itemize @bullet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7887 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7888 The first part is the name given to the function in Lisp, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7889 @code{delete-and-extract-region}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7890 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7891 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7892 The second part is the name of the function in C, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7893 @code{Fdelete_and_extract_region}. By convention, it starts with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7894 @samp{F}. Since C does not use hyphens in names, underscores are used |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7895 instead. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7896 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7897 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7898 The third part is the name for the C constant structure that records |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7899 information on this function for internal use. It is the name of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7900 function in C but begins with an @samp{S} instead of an @samp{F}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7901 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7902 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7903 The fourth and fifth parts specify the minimum and maximum number of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7904 arguments the function can have. This function demands exactly 2 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7905 arguments. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7906 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7907 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7908 The sixth part is nearly like the argument that follows the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7909 @code{interactive} declaration in a function written in Lisp: a letter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7910 followed, perhaps, by a prompt. The only difference from the Lisp is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7911 when the macro is called with no arguments. Then you write a @code{0} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7912 (which is a `null string'), as in this macro. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7913 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7914 If you were to specify arguments, you would place them between |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7915 quotation marks. The C macro for @code{goto-char} includes |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7916 @code{"NGoto char: "} in this position to indicate that the function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7917 expects a raw prefix, in this case, a numerical location in a buffer, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7918 and provides a prompt. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7919 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7920 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7921 The seventh part is a documentation string, just like the one for a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7922 function written in Emacs Lisp, except that every newline must be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7923 written explicitly as @samp{\n} followed by a backslash and carriage |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7924 return. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7925 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7926 @need 1000 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7927 Thus, the first two lines of documentation for @code{goto-char} are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7928 written like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7929 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7930 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7931 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7932 "Set point to POSITION, a number or marker.\n\ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7933 Beginning of buffer is position (point-min), end is (point-max). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7934 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7935 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7936 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7937 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7938 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7939 In a C macro, the formal parameters come next, with a statement of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7940 what kind of object they are, followed by what might be called the `body' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7941 of the macro. For @code{delete-and-extract-region} the `body' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7942 consists of the following two lines: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7943 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7944 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7945 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7946 validate_region (&start, &end); |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7947 return del_range_1 (XINT (start), XINT (end), 1, 1); |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7948 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7949 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7950 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7951 The first function, @code{validate_region} checks whether the values |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7952 passed as the beginning and end of the region are the proper type and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7953 are within range. The second function, @code{del_range_1}, actually |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7954 deletes the text. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7955 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7956 @code{del_range_1} is a complex function we will not look into. It |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7957 updates the buffer and does other things. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7958 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7959 However, it is worth looking at the two arguments passed to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7960 @code{del_range}. These are @w{@code{XINT (start)}} and @w{@code{XINT |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7961 (end)}}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7962 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7963 As far as the C language is concerned, @code{start} and @code{end} are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7964 two integers that mark the beginning and end of the region to be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7965 deleted@footnote{More precisely, and requiring more expert knowledge |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7966 to understand, the two integers are of type `Lisp_Object', which can |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7967 also be a C union instead of an integer type.}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7968 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7969 In early versions of Emacs, these two numbers were thirty-two bits |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7970 long, but the code is slowly being generalized to handle other |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7971 lengths. Three of the available bits are used to specify the type of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7972 information and a fourth bit is used for handling the computer's |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7973 memory; the remaining bits are used as `content'. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7974 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7975 @samp{XINT} is a C macro that extracts the relevant number from the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7976 longer collection of bits; the four other bits are discarded. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7977 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7978 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7979 The command in @code{delete-and-extract-region} looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7980 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7981 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7982 del_range_1 (XINT (start), XINT (end), 1, 1); |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7983 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7984 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7985 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7986 It deletes the region between the beginning position, @code{start}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7987 and the ending position, @code{end}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7988 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7989 From the point of view of the person writing Lisp, Emacs is all very |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7990 simple; but hidden underneath is a great deal of complexity to make it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7991 all work. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7992 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7993 @node defvar, copy-region-as-kill, Digression into C, Cutting & Storing Text |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7994 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7995 @section Initializing a Variable with @code{defvar} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7996 @findex defvar |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7997 @cindex Initializing a variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7998 @cindex Variable initialization |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
7999 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8000 Unlike the @code{delete-and-extract-region} function, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8001 @code{copy-region-as-kill} function is written in Emacs Lisp. Two |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8002 functions within it, @code{kill-append} and @code{kill-new}, copy a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8003 region in a buffer and save it in a variable called the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8004 @code{kill-ring}. This section describes how the @code{kill-ring} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8005 variable is created and initialized using the @code{defvar} special |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8006 form. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8007 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8008 (Again we note that the term @code{kill-ring} is a misnomer. The text |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8009 that is clipped out of the buffer can be brought back; it is not a ring |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8010 of corpses, but a ring of resurrectable text.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8011 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8012 In Emacs Lisp, a variable such as the @code{kill-ring} is created and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8013 given an initial value by using the @code{defvar} special form. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8014 name comes from ``define variable''. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8015 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8016 The @code{defvar} special form is similar to @code{setq} in that it sets |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8017 the value of a variable. It is unlike @code{setq} in two ways: first, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8018 it only sets the value of the variable if the variable does not already |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8019 have a value. If the variable already has a value, @code{defvar} does |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8020 not override the existing value. Second, @code{defvar} has a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8021 documentation string. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8022 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8023 (Another special form, @code{defcustom}, is designed for variables |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8024 that people customize. It has more features than @code{defvar}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8025 (@xref{defcustom, , Setting Variables with @code{defcustom}}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8026 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8027 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8028 * See variable current value:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8029 * defvar and asterisk:: An old-time convention. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8030 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8031 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8032 @node See variable current value, defvar and asterisk, defvar, defvar |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8033 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8034 @unnumberedsubsec Seeing the Current Value of a Variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8035 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8036 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8037 You can see the current value of a variable, any variable, by using |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8038 the @code{describe-variable} function, which is usually invoked by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8039 typing @kbd{C-h v}. If you type @kbd{C-h v} and then @code{kill-ring} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8040 (followed by @key{RET}) when prompted, you will see what is in your |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8041 current kill ring---this may be quite a lot! Conversely, if you have |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8042 been doing nothing this Emacs session except read this document, you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8043 may have nothing in it. Also, you will see the documentation for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8044 @code{kill-ring}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8045 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8046 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8047 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8048 Documentation: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8049 List of killed text sequences. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8050 Since the kill ring is supposed to interact nicely with cut-and-paste |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8051 facilities offered by window systems, use of this variable should |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8052 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8053 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8054 interact nicely with `interprogram-cut-function' and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8055 `interprogram-paste-function'. The functions `kill-new', |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8056 `kill-append', and `current-kill' are supposed to implement this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8057 interaction; you may want to use them instead of manipulating the kill |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8058 ring directly. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8059 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8060 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8061 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8062 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8063 The kill ring is defined by a @code{defvar} in the following way: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8064 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8065 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8066 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8067 (defvar kill-ring nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8068 "List of killed text sequences. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8069 @dots{}") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8070 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8071 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8072 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8073 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8074 In this variable definition, the variable is given an initial value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8075 @code{nil}, which makes sense, since if you have saved nothing, you want |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8076 nothing back if you give a @code{yank} command. The documentation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8077 string is written just like the documentation string of a @code{defun}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8078 As with the documentation string of the @code{defun}, the first line of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8079 the documentation should be a complete sentence, since some commands, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8080 like @code{apropos}, print only the first line of documentation. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8081 Succeeding lines should not be indented; otherwise they look odd when |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8082 you use @kbd{C-h v} (@code{describe-variable}). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8083 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8084 @node defvar and asterisk, , See variable current value, defvar |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8085 @subsection @code{defvar} and an asterisk |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8086 @findex defvar @r{for a user customizable variable} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8087 @findex defvar @r{with an asterisk} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8088 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8089 In the past, Emacs used the @code{defvar} special form both for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8090 internal variables that you would not expect a user to change and for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8091 variables that you do expect a user to change. Although you can still |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8092 use @code{defvar} for user customizable variables, please use |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8093 @code{defcustom} instead, since that special form provides a path into |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8094 the Customization commands. (@xref{defcustom, , Setting Variables |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8095 with @code{defcustom}}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8096 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8097 When you specified a variable using the @code{defvar} special form, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8098 you could distinguish a readily settable variable from others by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8099 typing an asterisk, @samp{*}, in the first column of its documentation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8100 string. For example: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8101 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8102 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8103 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8104 (defvar shell-command-default-error-buffer nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8105 "*Buffer name for `shell-command' @dots{} error output. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8106 @dots{} ") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8107 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8108 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8109 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8110 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8111 This means that you could (and still can) use the @code{edit-options} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8112 command to change the value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8113 @code{shell-command-default-error-buffer} temporarily. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8114 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8115 @findex edit-options |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8116 However, options set using @code{edit-options} are set only for the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8117 duration of your editing session. The new values are not saved |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8118 between sessions. Each time Emacs starts, it reads the original |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8119 value, unless you change the value within your @file{.emacs} file, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8120 either by setting it manually or by using @code{customize}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8121 @xref{Emacs Initialization, , Your @file{.emacs} File}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8122 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8123 For me, the major use of the @code{edit-options} command is to suggest |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8124 variables that I might want to set in my @file{.emacs} file. I urge |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8125 you to look through the list. (@xref{Edit Options, , Editing Variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8126 Values, emacs, The GNU Emacs Manual}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8127 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8128 @node copy-region-as-kill, cons & search-fwd Review, defvar, Cutting & Storing Text |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8129 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8130 @section @code{copy-region-as-kill} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8131 @findex copy-region-as-kill |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8132 @findex nthcdr |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8133 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8134 The @code{copy-region-as-kill} function copies a region of text from a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8135 buffer and (via either @code{kill-append} or @code{kill-new}) saves it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8136 in the @code{kill-ring}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8137 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8138 If you call @code{copy-region-as-kill} immediately after a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8139 @code{kill-region} command, Emacs appends the newly copied text to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8140 previously copied text. This means that if you yank back the text, you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8141 get it all, from both this and the previous operation. On the other |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8142 hand, if some other command precedes the @code{copy-region-as-kill}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8143 the function copies the text into a separate entry in the kill ring. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8144 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8145 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8146 * Complete copy-region-as-kill:: The complete function definition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8147 * copy-region-as-kill body:: The body of @code{copy-region-as-kill}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8148 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8149 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8150 @node Complete copy-region-as-kill, copy-region-as-kill body, copy-region-as-kill, copy-region-as-kill |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8151 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8152 @unnumberedsubsec The complete @code{copy-region-as-kill} function definition |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8153 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8154 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8155 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8156 Here is the complete text of the version 21 @code{copy-region-as-kill} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8157 function: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8158 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8159 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8160 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8161 (defun copy-region-as-kill (beg end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8162 "Save the region as if killed, but don't kill it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8163 In Transient Mark mode, deactivate the mark. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8164 If `interprogram-cut-function' is non-nil, also save |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8165 the text for a window system cut and paste." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8166 (interactive "r") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8167 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8168 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8169 (if (eq last-command 'kill-region) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8170 (kill-append (buffer-substring beg end) (< end beg)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8171 (kill-new (buffer-substring beg end))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8172 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8173 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8174 (if transient-mark-mode |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8175 (setq deactivate-mark t)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8176 nil) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8177 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8178 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8179 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8180 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8181 As usual, this function can be divided into its component parts: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8182 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8183 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8184 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8185 (defun copy-region-as-kill (@var{argument-list}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8186 "@var{documentation}@dots{}" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8187 (interactive "r") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8188 @var{body}@dots{}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8189 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8190 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8191 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8192 The arguments are @code{beg} and @code{end} and the function is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8193 interactive with @code{"r"}, so the two arguments must refer to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8194 beginning and end of the region. If you have been reading though this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8195 document from the beginning, understanding these parts of a function is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8196 almost becoming routine. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8197 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8198 The documentation is somewhat confusing unless you remember that the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8199 word `kill' has a meaning different from its usual meaning. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8200 `Transient Mark' and @code{interprogram-cut-function} comments explain |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8201 certain side-effects. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8202 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8203 After you once set a mark, a buffer always contains a region. If you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8204 wish, you can use Transient Mark mode to highlight the region |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8205 temporarily. (No one wants to highlight the region all the time, so |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8206 Transient Mark mode highlights it only at appropriate times. Many |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8207 people turn off Transient Mark mode, so the region is never |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8208 highlighted.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8209 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8210 Also, a windowing system allows you to copy, cut, and paste among |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8211 different programs. In the X windowing system, for example, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8212 @code{interprogram-cut-function} function is @code{x-select-text}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8213 which works with the windowing system's equivalent of the Emacs kill |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8214 ring. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8215 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8216 The body of the @code{copy-region-as-kill} function starts with an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8217 @code{if} clause. What this clause does is distinguish between two |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8218 different situations: whether or not this command is executed |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8219 immediately after a previous @code{kill-region} command. In the first |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8220 case, the new region is appended to the previously copied text. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8221 Otherwise, it is inserted into the beginning of the kill ring as a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8222 separate piece of text from the previous piece. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8223 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8224 The last two lines of the function prevent the region from lighting up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8225 if Transient Mark mode is turned on. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8226 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8227 The body of @code{copy-region-as-kill} merits discussion in detail. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8228 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8229 @node copy-region-as-kill body, , Complete copy-region-as-kill, copy-region-as-kill |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8230 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8231 @subsection The Body of @code{copy-region-as-kill} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8232 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8233 The @code{copy-region-as-kill} function works in much the same way as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8234 the @code{kill-region} function (@pxref{kill-region, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8235 ,@code{kill-region}}). Both are written so that two or more kills in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8236 a row combine their text into a single entry. If you yank back the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8237 text from the kill ring, you get it all in one piece. Moreover, kills |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8238 that kill forward from the current position of the cursor are added to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8239 the end of the previously copied text and commands that copy text |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8240 backwards add it to the beginning of the previously copied text. This |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8241 way, the words in the text stay in the proper order. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8242 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8243 Like @code{kill-region}, the @code{copy-region-as-kill} function makes |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8244 use of the @code{last-command} variable that keeps track of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8245 previous Emacs command. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8246 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8247 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8248 * last-command & this-command:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8249 * kill-append function:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8250 * kill-new function:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8251 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8252 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8253 @node last-command & this-command, kill-append function, copy-region-as-kill body, copy-region-as-kill body |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8254 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8255 @unnumberedsubsubsec @code{last-command} and @code{this-command} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8256 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8257 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8258 Normally, whenever a function is executed, Emacs sets the value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8259 @code{this-command} to the function being executed (which in this case |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8260 would be @code{copy-region-as-kill}). At the same time, Emacs sets |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8261 the value of @code{last-command} to the previous value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8262 @code{this-command}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8263 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8264 In the first part of the body of the @code{copy-region-as-kill} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8265 function, an @code{if} expression determines whether the value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8266 @code{last-command} is @code{kill-region}. If so, the then-part of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8267 the @code{if} expression is evaluated; it uses the @code{kill-append} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8268 function to concatenate the text copied at this call to the function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8269 with the text already in the first element (the @sc{car}) of the kill |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8270 ring. On the other hand, if the value of @code{last-command} is not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8271 @code{kill-region}, then the @code{copy-region-as-kill} function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8272 attaches a new element to the kill ring using the @code{kill-new} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8273 function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8274 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8275 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8276 The @code{if} expression reads as follows; it uses @code{eq}, which is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8277 a function we have not yet seen: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8278 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8279 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8280 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8281 (if (eq last-command 'kill-region) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8282 ;; @r{then-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8283 (kill-append (buffer-substring beg end) (< end beg)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8284 ;; @r{else-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8285 (kill-new (buffer-substring beg end))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8286 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8287 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8288 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8289 @findex eq @r{(example of use)} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8290 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8291 The @code{eq} function tests whether its first argument is the same Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8292 object as its second argument. The @code{eq} function is similar to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8293 @code{equal} function in that it is used to test for equality, but |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8294 differs in that it determines whether two representations are actually |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8295 the same object inside the computer, but with different names. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8296 @code{equal} determines whether the structure and contents of two |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8297 expressions are the same. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8298 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8299 If the previous command was @code{kill-region}, then the Emacs Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8300 interpreter calls the @code{kill-append} function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8301 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8302 @node kill-append function, kill-new function, last-command & this-command, copy-region-as-kill body |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8303 @unnumberedsubsubsec The @code{kill-append} function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8304 @findex kill-append |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8305 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8306 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8307 The @code{kill-append} function looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8308 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8309 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8310 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8311 (defun kill-append (string before-p) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8312 "Append STRING to the end of the latest kill in the kill ring. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8313 If BEFORE-P is non-nil, prepend STRING to the kill. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8314 If `interprogram-cut-function' is set, pass the resulting kill to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8315 it." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8316 (kill-new (if before-p |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8317 (concat string (car kill-ring)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8318 (concat (car kill-ring) string)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8319 t)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8320 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8321 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8322 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8323 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8324 The @code{kill-append} function is fairly straightforward. It uses |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8325 the @code{kill-new} function, which we will discuss in more detail in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8326 a moment. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8327 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8328 First, let us look at the conditional that is one of the two arguments |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8329 to @code{kill-new}. It uses @code{concat} to concatenate the new text |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8330 to the @sc{car} of the kill ring. Whether it prepends or appends the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8331 text depends on the results of an @code{if} expression: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8332 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8333 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8334 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8335 (if before-p ; @r{if-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8336 (concat string (car kill-ring)) ; @r{then-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8337 (concat (car kill-ring) string)) ; @r{else-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8338 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8339 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8340 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8341 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8342 If the region being killed is before the region that was killed in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8343 last command, then it should be prepended before the material that was |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8344 saved in the previous kill; and conversely, if the killed text follows |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8345 what was just killed, it should be appended after the previous text. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8346 The @code{if} expression depends on the predicate @code{before-p} to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8347 decide whether the newly saved text should be put before or after the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8348 previously saved text. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8349 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8350 The symbol @code{before-p} is the name of one of the arguments to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8351 @code{kill-append}. When the @code{kill-append} function is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8352 evaluated, it is bound to the value returned by evaluating the actual |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8353 argument. In this case, this is the expression @code{(< end beg)}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8354 This expression does not directly determine whether the killed text in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8355 this command is located before or after the kill text of the last |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8356 command; what is does is determine whether the value of the variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8357 @code{end} is less than the value of the variable @code{beg}. If it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8358 is, it means that the user is most likely heading towards the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8359 beginning of the buffer. Also, the result of evaluating the predicate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8360 expression, @code{(< end beg)}, will be true and the text will be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8361 prepended before the previous text. On the other hand, if the value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8362 the variable @code{end} is greater than the value of the variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8363 @code{beg}, the text will be appended after the previous text. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8364 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8365 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8366 When the newly saved text will be prepended, then the string with the new |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8367 text will be concatenated before the old text: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8368 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8369 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8370 (concat string (car kill-ring)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8371 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8372 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8373 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8374 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8375 But if the text will be appended, it will be concatenated |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8376 after the old text: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8377 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8378 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8379 (concat (car kill-ring) string)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8380 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8381 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8382 To understand how this works, we first need to review the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8383 @code{concat} function. The @code{concat} function links together or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8384 unites two strings of text. The result is a string. For example: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8385 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8386 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8387 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8388 (concat "abc" "def") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8389 @result{} "abcdef" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8390 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8391 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8392 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8393 (concat "new " |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8394 (car '("first element" "second element"))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8395 @result{} "new first element" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8396 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8397 (concat (car |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8398 '("first element" "second element")) " modified") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8399 @result{} "first element modified" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8400 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8401 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8402 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8403 We can now make sense of @code{kill-append}: it modifies the contents |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8404 of the kill ring. The kill ring is a list, each element of which is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8405 saved text. The @code{kill-append} function uses the @code{kill-new} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8406 function which in turn uses the @code{setcar} function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8407 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8408 @node kill-new function, , kill-append function, copy-region-as-kill body |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8409 @unnumberedsubsubsec The @code{kill-new} function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8410 @findex kill-new |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8411 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8412 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8413 The @code{kill-new} function looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8414 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8415 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8416 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8417 (defun kill-new (string &optional replace) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8418 "Make STRING the latest kill in the kill ring. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8419 Set the kill-ring-yank pointer to point to it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8420 If `interprogram-cut-function' is non-nil, apply it to STRING. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8421 Optional second argument REPLACE non-nil means that STRING will replace |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8422 the front of the kill ring, rather than being added to the list." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8423 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8424 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8425 (and (fboundp 'menu-bar-update-yank-menu) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8426 (menu-bar-update-yank-menu string (and replace (car kill-ring)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8427 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8428 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8429 (if (and replace kill-ring) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8430 (setcar kill-ring string) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8431 (setq kill-ring (cons string kill-ring)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8432 (if (> (length kill-ring) kill-ring-max) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8433 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8434 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8435 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8436 (setq kill-ring-yank-pointer kill-ring) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8437 (if interprogram-cut-function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8438 (funcall interprogram-cut-function string (not replace)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8439 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8440 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8441 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8442 As usual, we can look at this function in parts. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8443 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8444 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8445 The first line of the documentation makes sense: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8446 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8447 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8448 Make STRING the latest kill in the kill ring. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8449 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8450 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8451 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8452 Let's skip over the rest of the documentation for the moment. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8453 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8454 Also, let's skip over the first two lines of code, those involving |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8455 @code{menu-bar-update-yank-menu}. We will explain them below. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8456 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8457 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8458 The critical lines are these: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8459 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8460 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8461 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8462 (if (and replace kill-ring) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8463 ;; @r{then} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8464 (setcar kill-ring string) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8465 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8466 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8467 ;; @r{else} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8468 (setq kill-ring (cons string kill-ring)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8469 (if (> (length kill-ring) kill-ring-max) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8470 ;; @r{avoid overly long kill ring} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8471 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8472 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8473 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8474 (setq kill-ring-yank-pointer kill-ring) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8475 (if interprogram-cut-function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8476 (funcall interprogram-cut-function string (not replace)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8477 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8478 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8479 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8480 The conditional test is @w{@code{(and replace kill-ring)}}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8481 This will be true when two conditions are met: the kill ring has |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8482 something in it, and the @code{replace} variable is true. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8483 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8484 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8485 The @code{kill-append} function sets @code{replace} to be true; then, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8486 when the kill ring has at least one item in it, the @code{setcar} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8487 expression is executed: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8488 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8489 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8490 (setcar kill-ring string) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8491 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8492 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8493 The @code{setcar} function actually changes the first element of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8494 @code{kill-ring} list to the value of @code{string}. It replaces the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8495 first element. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8496 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8497 On the other hand, if the kill ring is empty, or replace is false, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8498 else-part of the condition is executed: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8499 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8500 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8501 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8502 (setq kill-ring (cons string kill-ring)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8503 (if (> (length kill-ring) kill-ring-max) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8504 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8505 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8506 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8507 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8508 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8509 This expression first constructs a new version of the kill ring by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8510 prepending @code{string} to the existing kill ring as a new element. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8511 Then it executes a second @code{if} clause. This second @code{if} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8512 clause keeps the kill ring from growing too long. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8513 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8514 Let's look at these two expressions in order. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8515 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8516 The @code{setq} line of the else-part sets the new value of the kill |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8517 ring to what results from adding the string being killed to the old kill |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8518 ring. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8519 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8520 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8521 We can see how this works with an example: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8522 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8523 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8524 (setq example-list '("here is a clause" "another clause")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8525 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8526 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8527 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8528 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8529 After evaluating this expression with @kbd{C-x C-e}, you can evaluate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8530 @code{example-list} and see what it returns: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8531 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8532 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8533 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8534 example-list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8535 @result{} ("here is a clause" "another clause") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8536 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8537 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8538 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8539 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8540 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8541 Now, we can add a new element on to this list by evaluating the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8542 following expression: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8543 @findex cons, @r{example} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8544 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8545 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8546 (setq example-list (cons "a third clause" example-list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8547 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8548 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8549 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8550 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8551 When we evaluate @code{example-list}, we find its value is: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8552 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8553 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8554 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8555 example-list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8556 @result{} ("a third clause" "here is a clause" "another clause") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8557 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8558 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8559 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8560 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8561 Thus, the third clause was added to the list by @code{cons}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8562 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8563 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8564 This is exactly similar to what the @code{setq} and @code{cons} do in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8565 the function. Here is the line again: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8566 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8567 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8568 (setq kill-ring (cons string kill-ring)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8569 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8570 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8571 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8572 Now for the second part of the @code{if} clause. This expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8573 keeps the kill ring from growing too long. It looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8574 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8575 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8576 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8577 (if (> (length kill-ring) kill-ring-max) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8578 (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8579 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8580 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8581 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8582 The code checks whether the length of the kill ring is greater than |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8583 the maximum permitted length. This is the value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8584 @code{kill-ring-max} (which is 60, by default). If the length of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8585 kill ring is too long, then this code sets the last element of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8586 kill ring to @code{nil}. It does this by using two functions, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8587 @code{nthcdr} and @code{setcdr}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8588 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8589 We looked at @code{setcdr} earlier (@pxref{setcdr, , @code{setcdr}}). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8590 It sets the @sc{cdr} of a list, just as @code{setcar} sets the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8591 @sc{car} of a list. In this case, however, @code{setcdr} will not be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8592 setting the @sc{cdr} of the whole kill ring; the @code{nthcdr} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8593 function is used to cause it to set the @sc{cdr} of the next to last |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8594 element of the kill ring---this means that since the @sc{cdr} of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8595 next to last element is the last element of the kill ring, it will set |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8596 the last element of the kill ring. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8597 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8598 @findex nthcdr, @r{example} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8599 The @code{nthcdr} function works by repeatedly taking the @sc{cdr} of a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8600 list---it takes the @sc{cdr} of the @sc{cdr} of the @sc{cdr} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8601 @dots{} It does this @var{N} times and returns the results. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8602 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8603 @findex setcdr, @r{example} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8604 Thus, if we had a four element list that was supposed to be three |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8605 elements long, we could set the @sc{cdr} of the next to last element |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8606 to @code{nil}, and thereby shorten the list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8607 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8608 You can see this by evaluating the following three expressions in turn. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8609 First set the value of @code{trees} to @code{(maple oak pine birch)}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8610 then set the @sc{cdr} of its second @sc{cdr} to @code{nil} and then |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8611 find the value of @code{trees}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8612 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8613 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8614 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8615 (setq trees '(maple oak pine birch)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8616 @result{} (maple oak pine birch) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8617 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8618 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8619 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8620 (setcdr (nthcdr 2 trees) nil) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8621 @result{} nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8622 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8623 trees |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8624 @result{} (maple oak pine) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8625 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8626 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8627 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8628 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8629 (The value returned by the @code{setcdr} expression is @code{nil} since |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8630 that is what the @sc{cdr} is set to.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8631 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8632 To repeat, in @code{kill-new}, the @code{nthcdr} function takes the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8633 @sc{cdr} a number of times that is one less than the maximum permitted |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8634 size of the kill ring and sets the @sc{cdr} of that element (which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8635 will be the rest of the elements in the kill ring) to @code{nil}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8636 This prevents the kill ring from growing too long. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8637 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8638 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8639 The next to last expression in the @code{kill-new} function is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8640 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8641 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8642 (setq kill-ring-yank-pointer kill-ring) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8643 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8644 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8645 The @code{kill-ring-yank-pointer} is a global variable that is set to be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8646 the @code{kill-ring}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8647 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8648 Even though the @code{kill-ring-yank-pointer} is called a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8649 @samp{pointer}, it is a variable just like the kill ring. However, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8650 name has been chosen to help humans understand how the variable is used. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8651 The variable is used in functions such as @code{yank} and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8652 @code{yank-pop} (@pxref{Yanking, , Yanking Text Back}). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8653 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8654 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8655 Now, to return to the first two lines in the body of the function: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8656 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8657 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8658 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8659 (and (fboundp 'menu-bar-update-yank-menu) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8660 (menu-bar-update-yank-menu string (and replace (car kill-ring)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8661 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8662 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8663 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8664 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8665 This is an expression whose first element is the function @code{and}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8666 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8667 @findex and, @r{introduced} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8668 The @code{and} special form evaluates each of its arguments until one of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8669 the arguments returns a value of @code{nil}, in which case the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8670 @code{and} expression returns @code{nil}; however, if none of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8671 arguments returns a value of @code{nil}, the value resulting from |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8672 evaluating the last argument is returned. (Since such a value is not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8673 @code{nil}, it is considered true in Emacs Lisp.) In other words, an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8674 @code{and} expression returns a true value only if all its arguments |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8675 are true. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8676 @findex and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8677 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8678 In this case, the expression tests first to see whether |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8679 @code{menu-bar-update-yank-menu} exists as a function, and if so, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8680 calls it. The @code{fboundp} function returns true if the symbol it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8681 is testing has a function definition that `is not void'. If the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8682 symbol's function definition were void, we would receive an error |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8683 message, as we did when we created errors intentionally (@pxref{Making |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8684 Errors, , Generate an Error Message}). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8685 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8686 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8687 Essentially, the @code{and} is an @code{if} expression that reads like |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8688 this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8689 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8690 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8691 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8692 if @var{the-menu-bar-function-exists} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8693 then @var{execute-it} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8694 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8695 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8696 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8697 @code{menu-bar-update-yank-menu} is one of the functions that make it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8698 possible to use the `Select and Paste' menu in the Edit item of a menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8699 bar; using a mouse, you can look at the various pieces of text you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8700 have saved and select one piece to paste. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8701 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8702 Finally, the last expression in the @code{kill-new} function adds the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8703 newly copied string to whatever facility exists for copying and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8704 pasting among different programs running in a windowing system. In |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8705 the X Windowing system, for example, the @code{x-select-text} function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8706 takes the string and stores it in memory operated by X. You can paste |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8707 the string in another program, such as an Xterm. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8708 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8709 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8710 The expression looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8711 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8712 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8713 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8714 (if interprogram-cut-function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8715 (funcall interprogram-cut-function string (not replace)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8716 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8717 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8718 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8719 If an @code{interprogram-cut-function} exists, then Emacs executes |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8720 @code{funcall}, which in turn calls its first argument as a function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8721 and passes the remaining arguments to it. (Incidentally, as far as I |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8722 can see, this @code{if} expression could be replaced by an @code{and} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8723 expression similar to the one in the first part of the function.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8724 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8725 We are not going to discuss windowing systems and other programs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8726 further, but merely note that this is a mechanism that enables GNU |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8727 Emacs to work easily and well with other programs. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8728 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8729 This code for placing text in the kill ring, either concatenated with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8730 an existing element or as a new element, leads us to the code for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8731 bringing back text that has been cut out of the buffer---the yank |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8732 commands. However, before discussing the yank commands, it is better |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8733 to learn how lists are implemented in a computer. This will make |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8734 clear such mysteries as the use of the term `pointer'. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8735 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8736 @node cons & search-fwd Review, search Exercises, copy-region-as-kill, Cutting & Storing Text |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8737 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8738 @section Review |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8739 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8740 Here is a brief summary of some recently introduced functions. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8741 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8742 @table @code |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8743 @item car |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8744 @itemx cdr |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8745 @code{car} returns the first element of a list; @code{cdr} returns the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8746 second and subsequent elements of a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8747 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8748 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8749 For example: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8750 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8751 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8752 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8753 (car '(1 2 3 4 5 6 7)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8754 @result{} 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8755 (cdr '(1 2 3 4 5 6 7)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8756 @result{} (2 3 4 5 6 7) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8757 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8758 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8759 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8760 @item cons |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8761 @code{cons} constructs a list by prepending its first argument to its |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8762 second argument. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8763 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8764 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8765 For example: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8766 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8767 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8768 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8769 (cons 1 '(2 3 4)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8770 @result{} (1 2 3 4) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8771 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8772 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8773 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8774 @item nthcdr |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8775 Return the result of taking @sc{cdr} `n' times on a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8776 @iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8777 The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8778 @tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8779 $n^{th}$ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8780 @end tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8781 @code{cdr}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8782 @end iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8783 The `rest of the rest', as it were. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8784 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8785 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8786 For example: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8787 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8788 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8789 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8790 (nthcdr 3 '(1 2 3 4 5 6 7)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8791 @result{} (4 5 6 7) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8792 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8793 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8794 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8795 @item setcar |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8796 @itemx setcdr |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8797 @code{setcar} changes the first element of a list; @code{setcdr} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8798 changes the second and subsequent elements of a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8799 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8800 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8801 For example: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8802 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8803 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8804 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8805 (setq triple '(1 2 3)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8806 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8807 (setcar triple '37) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8808 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8809 triple |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8810 @result{} (37 2 3) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8811 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8812 (setcdr triple '("foo" "bar")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8813 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8814 triple |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8815 @result{} (37 "foo" "bar") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8816 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8817 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8818 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8819 @item progn |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8820 Evaluate each argument in sequence and then return the value of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8821 last. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8822 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8823 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8824 For example: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8825 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8826 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8827 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8828 (progn 1 2 3 4) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8829 @result{} 4 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8830 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8831 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8832 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8833 @item save-restriction |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8834 Record whatever narrowing is in effect in the current buffer, if any, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8835 and restore that narrowing after evaluating the arguments. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8836 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8837 @item search-forward |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8838 Search for a string, and if the string is found, move point. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8839 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8840 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8841 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8842 Takes four arguments: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8843 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8844 @enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8845 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8846 The string to search for. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8847 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8848 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8849 Optionally, the limit of the search. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8850 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8851 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8852 Optionally, what to do if the search fails, return @code{nil} or an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8853 error message. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8854 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8855 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8856 Optionally, how many times to repeat the search; if negative, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8857 search goes backwards. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8858 @end enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8859 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8860 @item kill-region |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8861 @itemx delete-region |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8862 @itemx copy-region-as-kill |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8863 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8864 @code{kill-region} cuts the text between point and mark from the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8865 buffer and stores that text in the kill ring, so you can get it back |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8866 by yanking. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8867 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8868 @code{delete-and-extract-region} removes the text between point and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8869 mark from the buffer and throws it away. You cannot get it back. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8870 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8871 @code{copy-region-as-kill} copies the text between point and mark into |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8872 the kill ring, from which you can get it by yanking. The function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8873 does not cut or remove the text from the buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8874 @end table |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8875 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8876 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8877 @node search Exercises, , cons & search-fwd Review, Cutting & Storing Text |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8878 @section Searching Exercises |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8879 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8880 @itemize @bullet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8881 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8882 Write an interactive function that searches for a string. If the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8883 search finds the string, leave point after it and display a message |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8884 that says ``Found!''. (Do not use @code{search-forward} for the name |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8885 of this function; if you do, you will overwrite the existing version of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8886 @code{search-forward} that comes with Emacs. Use a name such as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8887 @code{test-search} instead.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8888 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8889 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8890 Write a function that prints the third element of the kill ring in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8891 echo area, if any; if the kill ring does not contain a third element, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8892 print an appropriate message. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8893 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8894 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8895 @node List Implementation, Yanking, Cutting & Storing Text, Top |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8896 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8897 @chapter How Lists are Implemented |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8898 @cindex Lists in a computer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8899 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8900 In Lisp, atoms are recorded in a straightforward fashion; if the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8901 implementation is not straightforward in practice, it is, nonetheless, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8902 straightforward in theory. The atom @samp{rose}, for example, is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8903 recorded as the four contiguous letters @samp{r}, @samp{o}, @samp{s}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8904 @samp{e}. A list, on the other hand, is kept differently. The mechanism |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8905 is equally simple, but it takes a moment to get used to the idea. A |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8906 list is kept using a series of pairs of pointers. In the series, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8907 first pointer in each pair points to an atom or to another list, and the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8908 second pointer in each pair points to the next pair, or to the symbol |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8909 @code{nil}, which marks the end of the list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8910 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8911 A pointer itself is quite simply the electronic address of what is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8912 pointed to. Hence, a list is kept as a series of electronic addresses. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8913 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8914 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8915 * Lists diagrammed:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8916 * Symbols as Chest:: Exploring a powerful metaphor. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8917 * List Exercise:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8918 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8919 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8920 @node Lists diagrammed, Symbols as Chest, List Implementation, List Implementation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8921 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8922 @unnumberedsec Lists diagrammed |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8923 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8924 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8925 For example, the list @code{(rose violet buttercup)} has three elements, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8926 @samp{rose}, @samp{violet}, and @samp{buttercup}. In the computer, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8927 electronic address of @samp{rose} is recorded in a segment of computer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8928 memory along with the address that gives the electronic address of where |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8929 the atom @samp{violet} is located; and that address (the one that tells |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8930 where @samp{violet} is located) is kept along with an address that tells |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8931 where the address for the atom @samp{buttercup} is located. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8932 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8933 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8934 This sounds more complicated than it is and is easier seen in a diagram: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8935 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8936 @c clear print-postscript-figures |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8937 @c !!! cons-cell-diagram #1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8938 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8939 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8940 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8941 ___ ___ ___ ___ ___ ___ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8942 |___|___|--> |___|___|--> |___|___|--> nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8943 | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8944 | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8945 --> rose --> violet --> buttercup |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8946 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8947 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8948 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8949 @ifset print-postscript-figures |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8950 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8951 @tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8952 @image{cons-1} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8953 %%%% old method of including an image |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8954 % \input /usr/local/lib/tex/inputs/psfig.tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8955 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-1.eps}} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8956 % \catcode`\@=0 % |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8957 @end tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8958 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8959 @end ifset |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8960 @ifclear print-postscript-figures |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8961 @iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8962 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8963 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8964 ___ ___ ___ ___ ___ ___ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8965 |___|___|--> |___|___|--> |___|___|--> nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8966 | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8967 | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8968 --> rose --> violet --> buttercup |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8969 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8970 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8971 @end iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8972 @end ifclear |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8973 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8974 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8975 In the diagram, each box represents a word of computer memory that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8976 holds a Lisp object, usually in the form of a memory address. The boxes, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8977 i.e.@: the addresses, are in pairs. Each arrow points to what the address |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8978 is the address of, either an atom or another pair of addresses. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8979 first box is the electronic address of @samp{rose} and the arrow points |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8980 to @samp{rose}; the second box is the address of the next pair of boxes, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8981 the first part of which is the address of @samp{violet} and the second |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8982 part of which is the address of the next pair. The very last box |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8983 points to the symbol @code{nil}, which marks the end of the list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8984 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8985 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8986 When a variable is set to a list with a function such as @code{setq}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8987 it stores the address of the first box in the variable. Thus, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8988 evaluation of the expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8989 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8990 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8991 (setq bouquet '(rose violet buttercup)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8992 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8993 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8994 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8995 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8996 creates a situation like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8997 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8998 @c cons-cell-diagram #2 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
8999 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9000 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9001 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9002 bouquet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9003 | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9004 | ___ ___ ___ ___ ___ ___ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9005 --> |___|___|--> |___|___|--> |___|___|--> nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9006 | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9007 | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9008 --> rose --> violet --> buttercup |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9009 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9010 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9011 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9012 @ifset print-postscript-figures |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9013 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9014 @tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9015 @image{cons-2} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9016 %%%% old method of including an image |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9017 % \input /usr/local/lib/tex/inputs/psfig.tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9018 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2.eps}} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9019 % \catcode`\@=0 % |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9020 @end tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9021 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9022 @end ifset |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9023 @ifclear print-postscript-figures |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9024 @iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9025 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9026 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9027 bouquet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9028 | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9029 | ___ ___ ___ ___ ___ ___ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9030 --> |___|___|--> |___|___|--> |___|___|--> nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9031 | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9032 | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9033 --> rose --> violet --> buttercup |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9034 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9035 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9036 @end iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9037 @end ifclear |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9038 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9039 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9040 In this example, the symbol @code{bouquet} holds the address of the first |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9041 pair of boxes. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9042 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9043 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9044 This same list can be illustrated in a different sort of box notation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9045 like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9046 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9047 @c cons-cell-diagram #2a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9048 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9049 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9050 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9051 bouquet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9052 | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9053 | -------------- --------------- ---------------- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9054 | | car | cdr | | car | cdr | | car | cdr | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9055 -->| rose | o------->| violet | o------->| butter- | nil | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9056 | | | | | | | cup | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9057 -------------- --------------- ---------------- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9058 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9059 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9060 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9061 @ifset print-postscript-figures |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9062 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9063 @tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9064 @image{cons-2a} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9065 %%%% old method of including an image |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9066 % \input /usr/local/lib/tex/inputs/psfig.tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9067 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2a.eps}} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9068 % \catcode`\@=0 % |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9069 @end tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9070 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9071 @end ifset |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9072 @ifclear print-postscript-figures |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9073 @iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9074 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9075 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9076 bouquet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9077 | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9078 | -------------- --------------- ---------------- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9079 | | car | cdr | | car | cdr | | car | cdr | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9080 -->| rose | o------->| violet | o------->| butter- | nil | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9081 | | | | | | | cup | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9082 -------------- --------------- ---------------- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9083 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9084 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9085 @end iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9086 @end ifclear |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9087 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9088 (Symbols consist of more than pairs of addresses, but the structure of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9089 a symbol is made up of addresses. Indeed, the symbol @code{bouquet} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9090 consists of a group of address-boxes, one of which is the address of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9091 the printed word @samp{bouquet}, a second of which is the address of a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9092 function definition attached to the symbol, if any, a third of which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9093 is the address of the first pair of address-boxes for the list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9094 @code{(rose violet buttercup)}, and so on. Here we are showing that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9095 the symbol's third address-box points to the first pair of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9096 address-boxes for the list.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9097 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9098 If a symbol is set to the @sc{cdr} of a list, the list itself is not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9099 changed; the symbol simply has an address further down the list. (In |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9100 the jargon, @sc{car} and @sc{cdr} are `non-destructive'.) Thus, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9101 evaluation of the following expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9102 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9103 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9104 (setq flowers (cdr bouquet)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9105 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9106 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9107 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9108 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9109 produces this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9110 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9111 @c cons-cell-diagram #3 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9112 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9113 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9114 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9115 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9116 bouquet flowers |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9117 | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9118 | ___ ___ | ___ ___ ___ ___ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9119 --> | | | --> | | | | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9120 |___|___|----> |___|___|--> |___|___|--> nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9121 | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9122 | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9123 --> rose --> violet --> buttercup |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9124 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9125 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9126 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9127 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9128 @ifset print-postscript-figures |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9129 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9130 @tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9131 @image{cons-3} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9132 %%%% old method of including an image |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9133 % \input /usr/local/lib/tex/inputs/psfig.tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9134 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-3.eps}} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9135 % \catcode`\@=0 % |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9136 @end tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9137 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9138 @end ifset |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9139 @ifclear print-postscript-figures |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9140 @iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9141 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9142 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9143 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9144 bouquet flowers |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9145 | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9146 | ___ ___ | ___ ___ ___ ___ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9147 --> | | | --> | | | | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9148 |___|___|----> |___|___|--> |___|___|--> nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9149 | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9150 | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9151 --> rose --> violet --> buttercup |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9152 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9153 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9154 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9155 @end iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9156 @end ifclear |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9157 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9158 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9159 The value of @code{flowers} is @code{(violet buttercup)}, which is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9160 to say, the symbol @code{flowers} holds the address of the pair of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9161 address-boxes, the first of which holds the address of @code{violet}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9162 and the second of which holds the address of @code{buttercup}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9163 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9164 A pair of address-boxes is called a @dfn{cons cell} or @dfn{dotted |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9165 pair}. @xref{List Type, , List Type , elisp, The GNU Emacs Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9166 Reference Manual}, and @ref{Dotted Pair Notation, , Dotted Pair |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9167 Notation, elisp, The GNU Emacs Lisp Reference Manual}, for more |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9168 information about cons cells and dotted pairs. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9169 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9170 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9171 The function @code{cons} adds a new pair of addresses to the front of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9172 a series of addresses like that shown above. For example, evaluating |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9173 the expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9174 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9175 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9176 (setq bouquet (cons 'lily bouquet)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9177 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9178 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9179 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9180 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9181 produces: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9182 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9183 @c cons-cell-diagram #4 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9184 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9185 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9186 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9187 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9188 bouquet flowers |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9189 | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9190 | ___ ___ ___ ___ | ___ ___ ___ ___ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9191 --> | | | | | | --> | | | | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9192 |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9193 | | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9194 | | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9195 --> lily --> rose --> violet --> buttercup |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9196 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9197 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9198 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9199 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9200 @ifset print-postscript-figures |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9201 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9202 @tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9203 @image{cons-4} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9204 %%%% old method of including an image |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9205 % \input /usr/local/lib/tex/inputs/psfig.tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9206 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-4.eps}} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9207 % \catcode`\@=0 % |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9208 @end tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9209 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9210 @end ifset |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9211 @ifclear print-postscript-figures |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9212 @iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9213 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9214 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9215 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9216 bouquet flowers |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9217 | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9218 | ___ ___ ___ ___ | ___ ___ ___ ___ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9219 --> | | | | | | --> | | | | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9220 |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9221 | | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9222 | | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9223 --> lily --> rose --> violet --> buttercup |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9224 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9225 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9226 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9227 @end iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9228 @end ifclear |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9229 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9230 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9231 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9232 However, this does not change the value of the symbol |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9233 @code{flowers}, as you can see by evaluating the following, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9234 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9235 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9236 (eq (cdr (cdr bouquet)) flowers) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9237 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9238 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9239 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9240 which returns @code{t} for true. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9241 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9242 Until it is reset, @code{flowers} still has the value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9243 @code{(violet buttercup)}; that is, it has the address of the cons |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9244 cell whose first address is of @code{violet}. Also, this does not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9245 alter any of the pre-existing cons cells; they are all still there. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9246 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9247 Thus, in Lisp, to get the @sc{cdr} of a list, you just get the address |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9248 of the next cons cell in the series; to get the @sc{car} of a list, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9249 you get the address of the first element of the list; to @code{cons} a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9250 new element on a list, you add a new cons cell to the front of the list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9251 That is all there is to it! The underlying structure of Lisp is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9252 brilliantly simple! |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9253 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9254 And what does the last address in a series of cons cells refer to? It |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9255 is the address of the empty list, of @code{nil}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9256 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9257 In summary, when a Lisp variable is set to a value, it is provided with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9258 the address of the list to which the variable refers. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9259 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9260 @node Symbols as Chest, List Exercise, Lists diagrammed, List Implementation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9261 @section Symbols as a Chest of Drawers |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9262 @cindex Symbols as a Chest of Drawers |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9263 @cindex Chest of Drawers, metaphor for a symbol |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9264 @cindex Drawers, Chest of, metaphor for a symbol |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9265 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9266 In an earlier section, I suggested that you might imagine a symbol as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9267 being a chest of drawers. The function definition is put in one |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9268 drawer, the value in another, and so on. What is put in the drawer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9269 holding the value can be changed without affecting the contents of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9270 drawer holding the function definition, and vice-versa. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9271 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9272 Actually, what is put in each drawer is the address of the value or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9273 function definition. It is as if you found an old chest in the attic, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9274 and in one of its drawers you found a map giving you directions to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9275 where the buried treasure lies. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9276 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9277 (In addition to its name, symbol definition, and variable value, a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9278 symbol has a `drawer' for a @dfn{property list} which can be used to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9279 record other information. Property lists are not discussed here; see |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9280 @ref{Property Lists, , Property Lists, elisp, The GNU Emacs Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9281 Reference Manual}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9282 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9283 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9284 Here is a fanciful representation: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9285 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9286 @c chest-of-drawers diagram |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9287 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9288 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9289 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9290 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9291 Chest of Drawers Contents of Drawers |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9292 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9293 __ o0O0o __ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9294 / \ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9295 --------------------- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9296 | directions to | [map to] |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9297 | symbol name | bouquet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9298 | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9299 +---------------------+ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9300 | directions to | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9301 | symbol definition | [none] |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9302 | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9303 +---------------------+ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9304 | directions to | [map to] |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9305 | variable value | (rose violet buttercup) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9306 | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9307 +---------------------+ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9308 | directions to | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9309 | property list | [not described here] |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9310 | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9311 +---------------------+ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9312 |/ \| |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9313 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9314 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9315 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9316 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9317 @ifset print-postscript-figures |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9318 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9319 @tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9320 @image{drawers} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9321 %%%% old method of including an image |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9322 % \input /usr/local/lib/tex/inputs/psfig.tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9323 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/drawers.eps}} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9324 % \catcode`\@=0 % |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9325 @end tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9326 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9327 @end ifset |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9328 @ifclear print-postscript-figures |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9329 @iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9330 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9331 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9332 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9333 Chest of Drawers Contents of Drawers |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9334 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9335 __ o0O0o __ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9336 / \ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9337 --------------------- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9338 | directions to | [map to] |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9339 | symbol name | bouquet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9340 | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9341 +---------------------+ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9342 | directions to | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9343 | symbol definition | [none] |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9344 | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9345 +---------------------+ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9346 | directions to | [map to] |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9347 | variable value | (rose violet buttercup) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9348 | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9349 +---------------------+ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9350 | directions to | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9351 | property list | [not described here] |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9352 | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9353 +---------------------+ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9354 |/ \| |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9355 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9356 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9357 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9358 @end iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9359 @end ifclear |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9360 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9361 @node List Exercise, , Symbols as Chest, List Implementation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9362 @section Exercise |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9363 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9364 Set @code{flowers} to @code{violet} and @code{buttercup}. Cons two |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9365 more flowers on to this list and set this new list to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9366 @code{more-flowers}. Set the @sc{car} of @code{flowers} to a fish. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9367 What does the @code{more-flowers} list now contain? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9368 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9369 @node Yanking, Loops & Recursion, List Implementation, Top |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9370 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9371 @chapter Yanking Text Back |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9372 @findex yank |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9373 @findex rotate-yank-pointer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9374 @cindex Text retrieval |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9375 @cindex Retrieving text |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9376 @cindex Pasting text |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9377 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9378 Whenever you cut text out of a buffer with a `kill' command in GNU Emacs, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9379 you can bring it back with a `yank' command. The text that is cut out of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9380 the buffer is put in the kill ring and the yank commands insert the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9381 appropriate contents of the kill ring back into a buffer (not necessarily |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9382 the original buffer). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9383 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9384 A simple @kbd{C-y} (@code{yank}) command inserts the first item from |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9385 the kill ring into the current buffer. If the @kbd{C-y} command is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9386 followed immediately by @kbd{M-y}, the first element is replaced by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9387 the second element. Successive @kbd{M-y} commands replace the second |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9388 element with the third, fourth, or fifth element, and so on. When the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9389 last element in the kill ring is reached, it is replaced by the first |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9390 element and the cycle is repeated. (Thus the kill ring is called a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9391 `ring' rather than just a `list'. However, the actual data structure |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9392 that holds the text is a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9393 @xref{Kill Ring, , Handling the Kill Ring}, for the details of how the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9394 list is handled as a ring.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9395 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9396 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9397 * Kill Ring Overview:: The kill ring is a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9398 * kill-ring-yank-pointer:: The @code{kill-ring-yank-pointer} variable. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9399 * yank nthcdr Exercises:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9400 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9401 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9402 @node Kill Ring Overview, kill-ring-yank-pointer, Yanking, Yanking |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9403 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9404 @section Kill Ring Overview |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9405 @cindex Kill ring overview |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9406 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9407 The kill ring is a list of textual strings. This is what it looks like: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9408 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9409 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9410 ("some text" "a different piece of text" "yet more text") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9411 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9412 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9413 If this were the contents of my kill ring and I pressed @kbd{C-y}, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9414 string of characters saying @samp{some text} would be inserted in this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9415 buffer where my cursor is located. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9416 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9417 The @code{yank} command is also used for duplicating text by copying it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9418 The copied text is not cut from the buffer, but a copy of it is put on the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9419 kill ring and is inserted by yanking it back. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9420 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9421 Three functions are used for bringing text back from the kill ring: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9422 @code{yank}, which is usually bound to @kbd{C-y}; @code{yank-pop}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9423 which is usually bound to @kbd{M-y}; and @code{rotate-yank-pointer}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9424 which is used by the two other functions. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9425 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9426 These functions refer to the kill ring through a variable called the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9427 @code{kill-ring-yank-pointer}. Indeed, the insertion code for both the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9428 @code{yank} and @code{yank-pop} functions is: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9429 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9430 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9431 (insert (car kill-ring-yank-pointer)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9432 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9433 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9434 To begin to understand how @code{yank} and @code{yank-pop} work, it is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9435 first necessary to look at the @code{kill-ring-yank-pointer} variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9436 and the @code{rotate-yank-pointer} function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9437 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9438 @node kill-ring-yank-pointer, yank nthcdr Exercises, Kill Ring Overview, Yanking |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9439 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9440 @section The @code{kill-ring-yank-pointer} Variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9441 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9442 @code{kill-ring-yank-pointer} is a variable, just as @code{kill-ring} is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9443 a variable. It points to something by being bound to the value of what |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9444 it points to, like any other Lisp variable. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9445 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9446 @need 1000 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9447 Thus, if the value of the kill ring is: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9448 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9449 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9450 ("some text" "a different piece of text" "yet more text") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9451 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9452 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9453 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9454 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9455 and the @code{kill-ring-yank-pointer} points to the second clause, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9456 value of @code{kill-ring-yank-pointer} is: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9457 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9458 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9459 ("a different piece of text" "yet more text") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9460 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9461 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9462 As explained in the previous chapter (@pxref{List Implementation}), the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9463 computer does not keep two different copies of the text being pointed to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9464 by both the @code{kill-ring} and the @code{kill-ring-yank-pointer}. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9465 words ``a different piece of text'' and ``yet more text'' are not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9466 duplicated. Instead, the two Lisp variables point to the same pieces of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9467 text. Here is a diagram: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9468 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9469 @c cons-cell-diagram #5 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9470 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9471 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9472 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9473 kill-ring kill-ring-yank-pointer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9474 | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9475 | ___ ___ | ___ ___ ___ ___ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9476 ---> | | | --> | | | | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9477 |___|___|----> |___|___|--> |___|___|--> nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9478 | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9479 | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9480 | | --> "yet more text" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9481 | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9482 | --> "a different piece of text |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9483 | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9484 --> "some text" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9485 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9486 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9487 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9488 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9489 @ifset print-postscript-figures |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9490 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9491 @tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9492 @image{cons-5} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9493 %%%% old method of including an image |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9494 % \input /usr/local/lib/tex/inputs/psfig.tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9495 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-5.eps}} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9496 % \catcode`\@=0 % |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9497 @end tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9498 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9499 @end ifset |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9500 @ifclear print-postscript-figures |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9501 @iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9502 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9503 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9504 kill-ring kill-ring-yank-pointer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9505 | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9506 | ___ ___ | ___ ___ ___ ___ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9507 ---> | | | --> | | | | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9508 |___|___|----> |___|___|--> |___|___|--> nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9509 | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9510 | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9511 | | --> "yet more text" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9512 | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9513 | --> "a different piece of text |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9514 | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9515 --> "some text" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9516 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9517 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9518 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9519 @end iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9520 @end ifclear |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9521 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9522 Both the variable @code{kill-ring} and the variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9523 @code{kill-ring-yank-pointer} are pointers. But the kill ring itself is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9524 usually described as if it were actually what it is composed of. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9525 @code{kill-ring} is spoken of as if it were the list rather than that it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9526 points to the list. Conversely, the @code{kill-ring-yank-pointer} is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9527 spoken of as pointing to a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9528 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9529 These two ways of talking about the same thing sound confusing at first but |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9530 make sense on reflection. The kill ring is generally thought of as the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9531 complete structure of data that holds the information of what has recently |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9532 been cut out of the Emacs buffers. The @code{kill-ring-yank-pointer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9533 on the other hand, serves to indicate---that is, to `point to'---that part |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9534 of the kill ring of which the first element (the @sc{car}) will be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9535 inserted. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9536 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9537 The @code{rotate-yank-pointer} function changes the element in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9538 kill ring to which the @code{kill-ring-yank-pointer} points; when the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9539 pointer is set to point to the next element beyond the end of the kill |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9540 ring, it automatically sets it to point to the first element of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9541 kill ring. This is how the list is transformed into a ring. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9542 @code{rotate-yank-pointer} function itself is not difficult, but |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9543 contains many details. It and the much simpler @code{yank} and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9544 @code{yank-pop} functions are described in an appendix. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9545 @xref{Kill Ring, , Handling the Kill Ring}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9546 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9547 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9548 @node yank nthcdr Exercises, , kill-ring-yank-pointer, Yanking |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9549 @section Exercises with @code{yank} and @code{nthcdr} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9550 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9551 @itemize @bullet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9552 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9553 Using @kbd{C-h v} (@code{describe-variable}), look at the value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9554 your kill ring. Add several items to your kill ring; look at its |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9555 value again. Using @kbd{M-y} (@code{yank-pop)}, move all the way |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9556 around the kill ring. How many items were in your kill ring? Find |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9557 the value of @code{kill-ring-max}. Was your kill ring full, or could |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9558 you have kept more blocks of text within it? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9559 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9560 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9561 Using @code{nthcdr} and @code{car}, construct a series of expressions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9562 to return the first, second, third, and fourth elements of a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9563 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9564 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9565 @node Loops & Recursion, Regexp Search, Yanking, Top |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9566 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9567 @chapter Loops and Recursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9568 @cindex Loops and recursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9569 @cindex Recursion and loops |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9570 @cindex Repetition (loops) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9571 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9572 Emacs Lisp has two primary ways to cause an expression, or a series of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9573 expressions, to be evaluated repeatedly: one uses a @code{while} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9574 loop, and the other uses @dfn{recursion}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9575 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9576 Repetition can be very valuable. For example, to move forward four |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9577 sentences, you need only write a program that will move forward one |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9578 sentence and then repeat the process four times. Since a computer does |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9579 not get bored or tired, such repetitive action does not have the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9580 deleterious effects that excessive or the wrong kinds of repetition can |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9581 have on humans. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9582 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9583 People mostly write Emacs Lisp functions using @code{while} loops and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9584 their kin; but you can use recursion, which provides a very powerful |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9585 way to think about and then to solve problems@footnote{You can write |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9586 recursive functions to be frugal or wasteful of mental or computer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9587 resources; as it happens, methods that people find easy---that are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9588 frugal of `mental resources'---sometimes use considerable computer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9589 resources. Emacs was designed to run on machines that we now consider |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9590 limited and its default settings are conservative. You may want to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9591 increase the values of @code{max-specpdl-size} and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9592 @code{max-lisp-eval-depth}. In my @file{.emacs} file, I set them to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9593 15 and 30 times their default value.}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9594 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9595 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9596 * while:: Causing a stretch of code to repeat. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9597 * dolist dotimes:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9598 * Recursion:: Causing a function to call itself. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9599 * Looping exercise:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9600 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9601 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9602 @node while, dolist dotimes, Loops & Recursion, Loops & Recursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9603 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9604 @section @code{while} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9605 @cindex Loops |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9606 @findex while |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9607 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9608 The @code{while} special form tests whether the value returned by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9609 evaluating its first argument is true or false. This is similar to what |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9610 the Lisp interpreter does with an @code{if}; what the interpreter does |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9611 next, however, is different. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9612 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9613 In a @code{while} expression, if the value returned by evaluating the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9614 first argument is false, the Lisp interpreter skips the rest of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9615 expression (the @dfn{body} of the expression) and does not evaluate it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9616 However, if the value is true, the Lisp interpreter evaluates the body |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9617 of the expression and then again tests whether the first argument to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9618 @code{while} is true or false. If the value returned by evaluating the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9619 first argument is again true, the Lisp interpreter again evaluates the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9620 body of the expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9621 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9622 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9623 The template for a @code{while} expression looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9624 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9625 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9626 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9627 (while @var{true-or-false-test} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9628 @var{body}@dots{}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9629 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9630 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9631 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9632 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9633 * Looping with while:: Repeat so long as test returns true. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9634 * Loop Example:: A @code{while} loop that uses a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9635 * print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9636 * Incrementing Loop:: A loop with an incrementing counter. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9637 * Decrementing Loop:: A loop with a decrementing counter. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9638 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9639 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9640 @node Looping with while, Loop Example, while, while |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9641 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9642 @unnumberedsubsec Looping with @code{while} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9643 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9644 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9645 So long as the true-or-false-test of the @code{while} expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9646 returns a true value when it is evaluated, the body is repeatedly |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9647 evaluated. This process is called a loop since the Lisp interpreter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9648 repeats the same thing again and again, like an airplane doing a loop. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9649 When the result of evaluating the true-or-false-test is false, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9650 Lisp interpreter does not evaluate the rest of the @code{while} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9651 expression and `exits the loop'. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9652 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9653 Clearly, if the value returned by evaluating the first argument to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9654 @code{while} is always true, the body following will be evaluated |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9655 again and again @dots{} and again @dots{} forever. Conversely, if the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9656 value returned is never true, the expressions in the body will never |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9657 be evaluated. The craft of writing a @code{while} loop consists of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9658 choosing a mechanism such that the true-or-false-test returns true |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9659 just the number of times that you want the subsequent expressions to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9660 be evaluated, and then have the test return false. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9661 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9662 The value returned by evaluating a @code{while} is the value of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9663 true-or-false-test. An interesting consequence of this is that a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9664 @code{while} loop that evaluates without error will return @code{nil} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9665 or false regardless of whether it has looped 1 or 100 times or none at |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9666 all. A @code{while} expression that evaluates successfully never |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9667 returns a true value! What this means is that @code{while} is always |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9668 evaluated for its side effects, which is to say, the consequences of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9669 evaluating the expressions within the body of the @code{while} loop. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9670 This makes sense. It is not the mere act of looping that is desired, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9671 but the consequences of what happens when the expressions in the loop |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9672 are repeatedly evaluated. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9673 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9674 @node Loop Example, print-elements-of-list, Looping with while, while |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9675 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9676 @subsection A @code{while} Loop and a List |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9677 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9678 A common way to control a @code{while} loop is to test whether a list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9679 has any elements. If it does, the loop is repeated; but if it does not, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9680 the repetition is ended. Since this is an important technique, we will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9681 create a short example to illustrate it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9682 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9683 A simple way to test whether a list has elements is to evaluate the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9684 list: if it has no elements, it is an empty list and will return the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9685 empty list, @code{()}, which is a synonym for @code{nil} or false. On |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9686 the other hand, a list with elements will return those elements when it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9687 is evaluated. Since Emacs Lisp considers as true any value that is not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9688 @code{nil}, a list that returns elements will test true in a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9689 @code{while} loop. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9690 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9691 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9692 For example, you can set the variable @code{empty-list} to @code{nil} by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9693 evaluating the following @code{setq} expression: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9694 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9695 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9696 (setq empty-list ()) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9697 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9698 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9699 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9700 After evaluating the @code{setq} expression, you can evaluate the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9701 variable @code{empty-list} in the usual way, by placing the cursor after |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9702 the symbol and typing @kbd{C-x C-e}; @code{nil} will appear in your |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9703 echo area: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9704 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9705 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9706 empty-list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9707 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9708 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9709 On the other hand, if you set a variable to be a list with elements, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9710 list will appear when you evaluate the variable, as you can see by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9711 evaluating the following two expressions: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9712 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9713 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9714 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9715 (setq animals '(gazelle giraffe lion tiger)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9716 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9717 animals |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9718 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9719 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9720 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9721 Thus, to create a @code{while} loop that tests whether there are any |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9722 items in the list @code{animals}, the first part of the loop will be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9723 written like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9724 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9725 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9726 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9727 (while animals |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9728 @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9729 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9730 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9731 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9732 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9733 When the @code{while} tests its first argument, the variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9734 @code{animals} is evaluated. It returns a list. So long as the list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9735 has elements, the @code{while} considers the results of the test to be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9736 true; but when the list is empty, it considers the results of the test |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9737 to be false. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9738 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9739 To prevent the @code{while} loop from running forever, some mechanism |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9740 needs to be provided to empty the list eventually. An oft-used |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9741 technique is to have one of the subsequent forms in the @code{while} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9742 expression set the value of the list to be the @sc{cdr} of the list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9743 Each time the @code{cdr} function is evaluated, the list will be made |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9744 shorter, until eventually only the empty list will be left. At this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9745 point, the test of the @code{while} loop will return false, and the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9746 arguments to the @code{while} will no longer be evaluated. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9747 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9748 For example, the list of animals bound to the variable @code{animals} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9749 can be set to be the @sc{cdr} of the original list with the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9750 following expression: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9751 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9752 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9753 (setq animals (cdr animals)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9754 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9755 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9756 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9757 If you have evaluated the previous expressions and then evaluate this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9758 expression, you will see @code{(giraffe lion tiger)} appear in the echo |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9759 area. If you evaluate the expression again, @code{(lion tiger)} will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9760 appear in the echo area. If you evaluate it again and yet again, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9761 @code{(tiger)} appears and then the empty list, shown by @code{nil}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9762 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9763 A template for a @code{while} loop that uses the @code{cdr} function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9764 repeatedly to cause the true-or-false-test eventually to test false |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9765 looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9766 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9767 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9768 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9769 (while @var{test-whether-list-is-empty} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9770 @var{body}@dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9771 @var{set-list-to-cdr-of-list}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9772 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9773 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9774 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9775 This test and use of @code{cdr} can be put together in a function that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9776 goes through a list and prints each element of the list on a line of its |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9777 own. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9778 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9779 @node print-elements-of-list, Incrementing Loop, Loop Example, while |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9780 @subsection An Example: @code{print-elements-of-list} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9781 @findex print-elements-of-list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9782 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9783 The @code{print-elements-of-list} function illustrates a @code{while} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9784 loop with a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9785 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9786 @cindex @file{*scratch*} buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9787 The function requires several lines for its output. If you are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9788 reading this in Emacs 21 or a later version, you can evaluate the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9789 following expression inside of Info, as usual. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9790 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9791 If you are using an earlier version of Emacs, you need to copy the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9792 necessary expressions to your @file{*scratch*} buffer and evaluate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9793 them there. This is because the echo area had only one line in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9794 earlier versions. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9795 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9796 You can copy the expressions by marking the beginning of the region |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9797 with @kbd{C-@key{SPC}} (@code{set-mark-command}), moving the cursor to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9798 the end of the region and then copying the region using @kbd{M-w} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9799 (@code{copy-region-as-kill}). In the @file{*scratch*} buffer, you can |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9800 yank the expressions back by typing @kbd{C-y} (@code{yank}). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9801 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9802 After you have copied the expressions to the @file{*scratch*} buffer, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9803 evaluate each expression in turn. Be sure to evaluate the last |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9804 expression, @code{(print-elements-of-list animals)}, by typing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9805 @kbd{C-u C-x C-e}, that is, by giving an argument to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9806 @code{eval-last-sexp}. This will cause the result of the evaluation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9807 to be printed in the @file{*scratch*} buffer instead of being printed |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9808 in the echo area. (Otherwise you will see something like this in your |
45663
046819540e6d
Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents:
44899
diff
changeset
|
9809 echo area: @code{^Jgazelle^J^Jgiraffe^J^Jlion^J^Jtiger^Jnil}, in which |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9810 each @samp{^J} stands for a `newline'.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9811 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9812 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9813 If you are using Emacs 21 or later, you can evaluate these expressions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9814 directly in the Info buffer, and the echo area will grow to show the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9815 results. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9816 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9817 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9818 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9819 (setq animals '(gazelle giraffe lion tiger)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9820 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9821 (defun print-elements-of-list (list) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9822 "Print each element of LIST on a line of its own." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9823 (while list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9824 (print (car list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9825 (setq list (cdr list)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9826 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9827 (print-elements-of-list animals) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9828 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9829 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9830 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9831 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9832 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9833 When you evaluate the three expressions in sequence, you will see |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9834 this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9835 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9836 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9837 @group |
45663
046819540e6d
Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents:
44899
diff
changeset
|
9838 gazelle |
046819540e6d
Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents:
44899
diff
changeset
|
9839 |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9840 giraffe |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9841 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9842 lion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9843 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9844 tiger |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9845 nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9846 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9847 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9848 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9849 Each element of the list is printed on a line of its own (that is what |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9850 the function @code{print} does) and then the value returned by the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9851 function is printed. Since the last expression in the function is the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9852 @code{while} loop, and since @code{while} loops always return |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9853 @code{nil}, a @code{nil} is printed after the last element of the list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9854 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9855 @node Incrementing Loop, Decrementing Loop, print-elements-of-list, while |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9856 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9857 @subsection A Loop with an Incrementing Counter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9858 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9859 A loop is not useful unless it stops when it ought. Besides |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9860 controlling a loop with a list, a common way of stopping a loop is to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9861 write the first argument as a test that returns false when the correct |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9862 number of repetitions are complete. This means that the loop must |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9863 have a counter---an expression that counts how many times the loop |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9864 repeats itself. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9865 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9866 The test can be an expression such as @code{(< count desired-number)} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9867 which returns @code{t} for true if the value of @code{count} is less |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9868 than the @code{desired-number} of repetitions and @code{nil} for false if |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9869 the value of @code{count} is equal to or is greater than the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9870 @code{desired-number}. The expression that increments the count can be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9871 a simple @code{setq} such as @code{(setq count (1+ count))}, where |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9872 @code{1+} is a built-in function in Emacs Lisp that adds 1 to its |
42506
d918430979ea
Put @w{...} around an expression with a poor printed copy page break.
Robert J. Chassell <bob@rattlesnake.com>
parents:
42109
diff
changeset
|
9873 argument. (The expression @w{@code{(1+ count)}} has the same result as |
42562
fb149efd0c72
Follow law precisely: four digits for all dates in copyright lines.
Robert J. Chassell <bob@rattlesnake.com>
parents:
42506
diff
changeset
|
9874 @w{@code{(+ count 1)}}, but is easier for a human to read.) |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9875 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9876 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9877 The template for a @code{while} loop controlled by an incrementing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9878 counter looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9879 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9880 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9881 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9882 @var{set-count-to-initial-value} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9883 (while (< count desired-number) ; @r{true-or-false-test} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9884 @var{body}@dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9885 (setq count (1+ count))) ; @r{incrementer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9886 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9887 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9888 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9889 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9890 Note that you need to set the initial value of @code{count}; usually it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9891 is set to 1. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9892 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9893 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9894 * Incrementing Example:: Counting pebbles in a triangle. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9895 * Inc Example parts:: The parts of the function definition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9896 * Inc Example altogether:: Putting the function definition together. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9897 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9898 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9899 @node Incrementing Example, Inc Example parts, Incrementing Loop, Incrementing Loop |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9900 @unnumberedsubsubsec Example with incrementing counter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9901 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9902 Suppose you are playing on the beach and decide to make a triangle of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9903 pebbles, putting one pebble in the first row, two in the second row, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9904 three in the third row and so on, like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9905 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9906 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9907 @c pebble diagram |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9908 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9909 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9910 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9911 * |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9912 * * |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9913 * * * |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9914 * * * * |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9915 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9916 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9917 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9918 @iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9919 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9920 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9921 @bullet{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9922 @bullet{} @bullet{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9923 @bullet{} @bullet{} @bullet{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9924 @bullet{} @bullet{} @bullet{} @bullet{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9925 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9926 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9927 @end iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9928 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9929 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9930 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9931 (About 2500 years ago, Pythagoras and others developed the beginnings of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9932 number theory by considering questions such as this.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9933 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9934 Suppose you want to know how many pebbles you will need to make a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9935 triangle with 7 rows? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9936 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9937 Clearly, what you need to do is add up the numbers from 1 to 7. There |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9938 are two ways to do this; start with the smallest number, one, and add up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9939 the list in sequence, 1, 2, 3, 4 and so on; or start with the largest |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9940 number and add the list going down: 7, 6, 5, 4 and so on. Because both |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9941 mechanisms illustrate common ways of writing @code{while} loops, we will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9942 create two examples, one counting up and the other counting down. In |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9943 this first example, we will start with 1 and add 2, 3, 4 and so on. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9944 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9945 If you are just adding up a short list of numbers, the easiest way to do |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9946 it is to add up all the numbers at once. However, if you do not know |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9947 ahead of time how many numbers your list will have, or if you want to be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9948 prepared for a very long list, then you need to design your addition so |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9949 that what you do is repeat a simple process many times instead of doing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9950 a more complex process once. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9951 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9952 For example, instead of adding up all the pebbles all at once, what you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9953 can do is add the number of pebbles in the first row, 1, to the number |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9954 in the second row, 2, and then add the total of those two rows to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9955 third row, 3. Then you can add the number in the fourth row, 4, to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9956 total of the first three rows; and so on. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9957 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9958 The critical characteristic of the process is that each repetitive |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9959 action is simple. In this case, at each step we add only two numbers, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9960 the number of pebbles in the row and the total already found. This |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9961 process of adding two numbers is repeated again and again until the last |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9962 row has been added to the total of all the preceding rows. In a more |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9963 complex loop the repetitive action might not be so simple, but it will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9964 be simpler than doing everything all at once. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9965 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9966 @node Inc Example parts, Inc Example altogether, Incrementing Example, Incrementing Loop |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9967 @unnumberedsubsubsec The parts of the function definition |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9968 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9969 The preceding analysis gives us the bones of our function definition: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9970 first, we will need a variable that we can call @code{total} that will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9971 be the total number of pebbles. This will be the value returned by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9972 the function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9973 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9974 Second, we know that the function will require an argument: this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9975 argument will be the total number of rows in the triangle. It can be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9976 called @code{number-of-rows}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9977 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9978 Finally, we need a variable to use as a counter. We could call this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9979 variable @code{counter}, but a better name is @code{row-number}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9980 That is because what the counter does is count rows, and a program |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9981 should be written to be as understandable as possible. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9982 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9983 When the Lisp interpreter first starts evaluating the expressions in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9984 function, the value of @code{total} should be set to zero, since we have |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9985 not added anything to it. Then the function should add the number of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9986 pebbles in the first row to the total, and then add the number of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9987 pebbles in the second to the total, and then add the number of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9988 pebbles in the third row to the total, and so on, until there are no |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9989 more rows left to add. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9990 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9991 Both @code{total} and @code{row-number} are used only inside the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9992 function, so they can be declared as local variables with @code{let} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9993 and given initial values. Clearly, the initial value for @code{total} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9994 should be 0. The initial value of @code{row-number} should be 1, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9995 since we start with the first row. This means that the @code{let} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9996 statement will look like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9997 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9998 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
9999 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10000 (let ((total 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10001 (row-number 1)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10002 @var{body}@dots{}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10003 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10004 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10005 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10006 After the internal variables are declared and bound to their initial |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10007 values, we can begin the @code{while} loop. The expression that serves |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10008 as the test should return a value of @code{t} for true so long as the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10009 @code{row-number} is less than or equal to the @code{number-of-rows}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10010 (If the expression tests true only so long as the row number is less |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10011 than the number of rows in the triangle, the last row will never be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10012 added to the total; hence the row number has to be either less than or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10013 equal to the number of rows.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10014 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10015 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10016 @findex <= @r{(less than or equal)} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10017 Lisp provides the @code{<=} function that returns true if the value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10018 its first argument is less than or equal to the value of its second |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10019 argument and false otherwise. So the expression that the @code{while} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10020 will evaluate as its test should look like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10021 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10022 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10023 (<= row-number number-of-rows) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10024 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10025 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10026 The total number of pebbles can be found by repeatedly adding the number |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10027 of pebbles in a row to the total already found. Since the number of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10028 pebbles in the row is equal to the row number, the total can be found by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10029 adding the row number to the total. (Clearly, in a more complex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10030 situation, the number of pebbles in the row might be related to the row |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10031 number in a more complicated way; if this were the case, the row number |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10032 would be replaced by the appropriate expression.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10033 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10034 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10035 (setq total (+ total row-number)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10036 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10037 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10038 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10039 What this does is set the new value of @code{total} to be equal to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10040 sum of adding the number of pebbles in the row to the previous total. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10041 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10042 After setting the value of @code{total}, the conditions need to be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10043 established for the next repetition of the loop, if there is one. This |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10044 is done by incrementing the value of the @code{row-number} variable, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10045 which serves as a counter. After the @code{row-number} variable has |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10046 been incremented, the true-or-false-test at the beginning of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10047 @code{while} loop tests whether its value is still less than or equal to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10048 the value of the @code{number-of-rows} and if it is, adds the new value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10049 of the @code{row-number} variable to the @code{total} of the previous |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10050 repetition of the loop. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10051 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10052 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10053 The built-in Emacs Lisp function @code{1+} adds 1 to a number, so the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10054 @code{row-number} variable can be incremented with this expression: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10055 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10056 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10057 (setq row-number (1+ row-number)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10058 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10059 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10060 @node Inc Example altogether, , Inc Example parts, Incrementing Loop |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10061 @unnumberedsubsubsec Putting the function definition together |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10062 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10063 We have created the parts for the function definition; now we need to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10064 put them together. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10065 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10066 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10067 First, the contents of the @code{while} expression: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10068 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10069 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10070 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10071 (while (<= row-number number-of-rows) ; @r{true-or-false-test} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10072 (setq total (+ total row-number)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10073 (setq row-number (1+ row-number))) ; @r{incrementer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10074 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10075 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10076 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10077 Along with the @code{let} expression varlist, this very nearly |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10078 completes the body of the function definition. However, it requires |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10079 one final element, the need for which is somewhat subtle. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10080 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10081 The final touch is to place the variable @code{total} on a line by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10082 itself after the @code{while} expression. Otherwise, the value returned |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10083 by the whole function is the value of the last expression that is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10084 evaluated in the body of the @code{let}, and this is the value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10085 returned by the @code{while}, which is always @code{nil}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10086 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10087 This may not be evident at first sight. It almost looks as if the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10088 incrementing expression is the last expression of the whole function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10089 But that expression is part of the body of the @code{while}; it is the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10090 last element of the list that starts with the symbol @code{while}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10091 Moreover, the whole of the @code{while} loop is a list within the body |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10092 of the @code{let}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10093 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10094 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10095 In outline, the function will look like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10096 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10097 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10098 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10099 (defun @var{name-of-function} (@var{argument-list}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10100 "@var{documentation}@dots{}" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10101 (let (@var{varlist}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10102 (while (@var{true-or-false-test}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10103 @var{body-of-while}@dots{} ) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10104 @dots{} ) ; @r{Need final expression here.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10105 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10106 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10107 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10108 The result of evaluating the @code{let} is what is going to be returned |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10109 by the @code{defun} since the @code{let} is not embedded within any |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10110 containing list, except for the @code{defun} as a whole. However, if |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10111 the @code{while} is the last element of the @code{let} expression, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10112 function will always return @code{nil}. This is not what we want! |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10113 Instead, what we want is the value of the variable @code{total}. This |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10114 is returned by simply placing the symbol as the last element of the list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10115 starting with @code{let}. It gets evaluated after the preceding |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10116 elements of the list are evaluated, which means it gets evaluated after |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10117 it has been assigned the correct value for the total. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10118 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10119 It may be easier to see this by printing the list starting with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10120 @code{let} all on one line. This format makes it evident that the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10121 @var{varlist} and @code{while} expressions are the second and third |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10122 elements of the list starting with @code{let}, and the @code{total} is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10123 the last element: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10124 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10125 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10126 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10127 (let (@var{varlist}) (while (@var{true-or-false-test}) @var{body-of-while}@dots{} ) total) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10128 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10129 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10130 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10131 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10132 Putting everything together, the @code{triangle} function definition |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10133 looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10134 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10135 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10136 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10137 (defun triangle (number-of-rows) ; @r{Version with} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10138 ; @r{ incrementing counter.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10139 "Add up the number of pebbles in a triangle. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10140 The first row has one pebble, the second row two pebbles, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10141 the third row three pebbles, and so on. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10142 The argument is NUMBER-OF-ROWS." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10143 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10144 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10145 (let ((total 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10146 (row-number 1)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10147 (while (<= row-number number-of-rows) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10148 (setq total (+ total row-number)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10149 (setq row-number (1+ row-number))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10150 total)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10151 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10152 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10153 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10154 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10155 After you have installed @code{triangle} by evaluating the function, you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10156 can try it out. Here are two examples: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10157 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10158 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10159 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10160 (triangle 4) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10161 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10162 (triangle 7) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10163 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10164 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10165 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10166 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10167 The sum of the first four numbers is 10 and the sum of the first seven |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10168 numbers is 28. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10169 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10170 @node Decrementing Loop, , Incrementing Loop, while |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10171 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10172 @subsection Loop with a Decrementing Counter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10173 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10174 Another common way to write a @code{while} loop is to write the test |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10175 so that it determines whether a counter is greater than zero. So long |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10176 as the counter is greater than zero, the loop is repeated. But when |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10177 the counter is equal to or less than zero, the loop is stopped. For |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10178 this to work, the counter has to start out greater than zero and then |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10179 be made smaller and smaller by a form that is evaluated |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10180 repeatedly. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10181 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10182 The test will be an expression such as @code{(> counter 0)} which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10183 returns @code{t} for true if the value of @code{counter} is greater |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10184 than zero, and @code{nil} for false if the value of @code{counter} is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10185 equal to or less than zero. The expression that makes the number |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10186 smaller and smaller can be a simple @code{setq} such as @code{(setq |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10187 counter (1- counter))}, where @code{1-} is a built-in function in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10188 Emacs Lisp that subtracts 1 from its argument. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10189 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10190 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10191 The template for a decrementing @code{while} loop looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10192 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10193 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10194 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10195 (while (> counter 0) ; @r{true-or-false-test} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10196 @var{body}@dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10197 (setq counter (1- counter))) ; @r{decrementer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10198 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10199 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10201 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10202 * Decrementing Example:: More pebbles on the beach. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10203 * Dec Example parts:: The parts of the function definition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10204 * Dec Example altogether:: Putting the function definition together. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10205 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10206 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10207 @node Decrementing Example, Dec Example parts, Decrementing Loop, Decrementing Loop |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10208 @unnumberedsubsubsec Example with decrementing counter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10209 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10210 To illustrate a loop with a decrementing counter, we will rewrite the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10211 @code{triangle} function so the counter decreases to zero. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10212 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10213 This is the reverse of the earlier version of the function. In this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10214 case, to find out how many pebbles are needed to make a triangle with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10215 3 rows, add the number of pebbles in the third row, 3, to the number |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10216 in the preceding row, 2, and then add the total of those two rows to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10217 the row that precedes them, which is 1. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10218 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10219 Likewise, to find the number of pebbles in a triangle with 7 rows, add |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10220 the number of pebbles in the seventh row, 7, to the number in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10221 preceding row, which is 6, and then add the total of those two rows to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10222 the row that precedes them, which is 5, and so on. As in the previous |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10223 example, each addition only involves adding two numbers, the total of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10224 the rows already added up and the number of pebbles in the row that is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10225 being added to the total. This process of adding two numbers is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10226 repeated again and again until there are no more pebbles to add. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10227 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10228 We know how many pebbles to start with: the number of pebbles in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10229 last row is equal to the number of rows. If the triangle has seven |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10230 rows, the number of pebbles in the last row is 7. Likewise, we know how |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10231 many pebbles are in the preceding row: it is one less than the number in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10232 the row. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10233 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10234 @node Dec Example parts, Dec Example altogether, Decrementing Example, Decrementing Loop |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10235 @unnumberedsubsubsec The parts of the function definition |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10236 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10237 We start with three variables: the total number of rows in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10238 triangle; the number of pebbles in a row; and the total number of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10239 pebbles, which is what we want to calculate. These variables can be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10240 named @code{number-of-rows}, @code{number-of-pebbles-in-row}, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10241 @code{total}, respectively. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10242 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10243 Both @code{total} and @code{number-of-pebbles-in-row} are used only |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10244 inside the function and are declared with @code{let}. The initial |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10245 value of @code{total} should, of course, be zero. However, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10246 initial value of @code{number-of-pebbles-in-row} should be equal to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10247 the number of rows in the triangle, since the addition will start with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10248 the longest row. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10249 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10250 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10251 This means that the beginning of the @code{let} expression will look |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10252 like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10253 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10254 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10255 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10256 (let ((total 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10257 (number-of-pebbles-in-row number-of-rows)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10258 @var{body}@dots{}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10259 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10260 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10261 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10262 The total number of pebbles can be found by repeatedly adding the number |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10263 of pebbles in a row to the total already found, that is, by repeatedly |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10264 evaluating the following expression: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10265 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10266 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10267 (setq total (+ total number-of-pebbles-in-row)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10268 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10269 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10270 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10271 After the @code{number-of-pebbles-in-row} is added to the @code{total}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10272 the @code{number-of-pebbles-in-row} should be decremented by one, since |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10273 the next time the loop repeats, the preceding row will be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10274 added to the total. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10275 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10276 The number of pebbles in a preceding row is one less than the number of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10277 pebbles in a row, so the built-in Emacs Lisp function @code{1-} can be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10278 used to compute the number of pebbles in the preceding row. This can be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10279 done with the following expression: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10280 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10281 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10282 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10283 (setq number-of-pebbles-in-row |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10284 (1- number-of-pebbles-in-row)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10285 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10286 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10287 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10288 Finally, we know that the @code{while} loop should stop making repeated |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10289 additions when there are no pebbles in a row. So the test for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10290 the @code{while} loop is simply: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10291 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10292 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10293 (while (> number-of-pebbles-in-row 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10294 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10295 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10296 @node Dec Example altogether, , Dec Example parts, Decrementing Loop |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10297 @unnumberedsubsubsec Putting the function definition together |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10298 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10299 We can put these expressions together to create a function definition |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10300 that works. However, on examination, we find that one of the local |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10301 variables is unneeded! |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10302 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10303 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10304 The function definition looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10305 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10306 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10307 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10308 ;;; @r{First subtractive version.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10309 (defun triangle (number-of-rows) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10310 "Add up the number of pebbles in a triangle." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10311 (let ((total 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10312 (number-of-pebbles-in-row number-of-rows)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10313 (while (> number-of-pebbles-in-row 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10314 (setq total (+ total number-of-pebbles-in-row)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10315 (setq number-of-pebbles-in-row |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10316 (1- number-of-pebbles-in-row))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10317 total)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10318 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10319 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10320 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10321 As written, this function works. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10322 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10323 However, we do not need @code{number-of-pebbles-in-row}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10324 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10325 @cindex Argument as local variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10326 When the @code{triangle} function is evaluated, the symbol |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10327 @code{number-of-rows} will be bound to a number, giving it an initial |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10328 value. That number can be changed in the body of the function as if |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10329 it were a local variable, without any fear that such a change will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10330 effect the value of the variable outside of the function. This is a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10331 very useful characteristic of Lisp; it means that the variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10332 @code{number-of-rows} can be used anywhere in the function where |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10333 @code{number-of-pebbles-in-row} is used. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10334 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10335 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10336 Here is a second version of the function written a bit more cleanly: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10337 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10338 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10339 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10340 (defun triangle (number) ; @r{Second version.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10341 "Return sum of numbers 1 through NUMBER inclusive." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10342 (let ((total 0)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10343 (while (> number 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10344 (setq total (+ total number)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10345 (setq number (1- number))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10346 total)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10347 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10348 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10349 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10350 In brief, a properly written @code{while} loop will consist of three parts: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10351 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10352 @enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10353 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10354 A test that will return false after the loop has repeated itself the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10355 correct number of times. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10356 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10357 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10358 An expression the evaluation of which will return the value desired |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10359 after being repeatedly evaluated. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10360 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10361 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10362 An expression to change the value passed to the true-or-false-test so |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10363 that the test returns false after the loop has repeated itself the right |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10364 number of times. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10365 @end enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10366 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10367 @node dolist dotimes, Recursion, while, Loops & Recursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10368 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10369 @section Save your time: @code{dolist} and @code{dotimes} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10370 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10371 In addition to @code{while}, both @code{dolist} and @code{dotimes} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10372 provide for looping. Sometimes these are quicker to write than the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10373 equivalent @code{while} loop. Both are Lisp macros. (@xref{Macros, , |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10374 Macros, elisp, The GNU Emacs Lisp Reference Manual}. ) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10375 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10376 @code{dolist} works like a @code{while} loop that `@sc{cdr}s down a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10377 list': @code{dolist} automatically shortens the list each time it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10378 loops---takes the @sc{cdr} of the list---and binds the @sc{car} of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10379 each shorter version of the list to the first of its arguments. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10380 |
44899
ebddb2618c17
Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents:
43431
diff
changeset
|
10381 @code{dotimes} loops a specific number of times: you specify the number. |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10382 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10383 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10384 * dolist:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10385 * dotimes:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10386 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10387 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10388 @node dolist, dotimes, dolist dotimes, dolist dotimes |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10389 @unnumberedsubsubsec The @code{dolist} Macro |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10390 @findex dolist |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10391 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10392 Suppose, for example, you want to reverse a list, so that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10393 ``first'' ``second'' ``third'' becomes ``third'' ``second'' ``first''. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10394 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10395 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10396 In practice, you would use the @code{reverse} function, like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10397 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10398 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10399 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10400 (setq animals '(gazelle giraffe lion tiger)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10401 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10402 (reverse animals) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10403 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10404 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10405 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10406 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10407 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10408 Here is how you could reverse the list using a @code{while} loop: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10409 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10410 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10411 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10412 (setq animals '(gazelle giraffe lion tiger)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10413 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10414 (defun reverse-list-with-while (list) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10415 "Using while, reverse the order of LIST." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10416 (let (value) ; make sure list starts empty |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10417 (while list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10418 (setq value (cons (car list) value)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10419 (setq list (cdr list))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10420 value)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10421 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10422 (reverse-list-with-while animals) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10423 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10424 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10425 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10426 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10427 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10428 And here is how you could use the @code{dolist} macro: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10429 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10430 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10431 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10432 (setq animals '(gazelle giraffe lion tiger)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10433 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10434 (defun reverse-list-with-dolist (list) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10435 "Using dolist, reverse the order of LIST." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10436 (let (value) ; make sure list starts empty |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10437 (dolist (element list value) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10438 (setq value (cons element value))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10439 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10440 (reverse-list-with-dolist animals) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10441 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10442 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10443 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10444 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10445 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10446 In Info, you can place your cursor after the closing parenthesis of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10447 each expression and type @kbd{C-x C-e}; in each case, you should see |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10448 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10449 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10450 (tiger lion giraffe gazelle) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10451 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10452 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10453 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10454 in the echo area. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10455 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10456 For this example, the existing @code{reverse} function is obviously best. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10457 The @code{while} loop is just like our first example (@pxref{Loop |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10458 Example, , A @code{while} Loop and a List}). The @code{while} first |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10459 checks whether the list has elements; if so, it constructs a new list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10460 by adding the first element of the list to the existing list (which in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10461 the first iteration of the loop is @code{nil}). Since the second |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10462 element is prepended in front of the first element, and the third |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10463 element is prepended in front of the second element, the list is reversed. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10464 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10465 In the expression using a @code{while} loop, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10466 the @w{@code{(setq list (cdr list))}} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10467 expression shortens the list, so the @code{while} loop eventually |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10468 stops. In addition, it provides the @code{cons} expression with a new |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10469 first element by creating a new and shorter list at each repetition of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10470 the loop. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10471 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10472 The @code{dolist} expression does very much the same as the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10473 @code{while} expression, except that the @code{dolist} macro does some |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10474 of the work you have to do when writing a @code{while} expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10475 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10476 Like a @code{while} loop, a @code{dolist} loops. What is different is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10477 that it automatically shortens the list each time it loops --- it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10478 `@sc{cdr}s down the list' on its own --- and it automatically binds |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10479 the @sc{car} of each shorter version of the list to the first of its |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10480 arguments. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10481 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10482 In the example, the @sc{car} of each shorter version of the list is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10483 referred to using the symbol @samp{element}, the list itself is called |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10484 @samp{list}, and the value returned is called @samp{value}. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10485 remainder of the @code{dolist} expression is the body. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10486 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10487 The @code{dolist} expression binds the @sc{car} of each shorter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10488 version of the list to @code{element} and then evaluates the body of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10489 the expression; and repeats the loop. The result is returned in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10490 @code{value}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10491 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10492 @node dotimes, , dolist, dolist dotimes |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10493 @unnumberedsubsubsec The @code{dotimes} Macro |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10494 @findex dotimes |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10495 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10496 The @code{dotimes} macro is similar to @code{dolist}, except that it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10497 loops a specific number of times. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10498 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10499 The first argument to @code{dotimes} is assigned the numbers 0, 1, 2 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10500 and so forth each time around the loop, and the value of the third |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10501 argument is returned. You need to provide the value of the second |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10502 argument, which is how many times the macro loops. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10503 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10504 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10505 For example, the following binds the numbers from 0 up to, but not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10506 including, the number 3 to the first argument, @var{number}, and then |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10507 constructs a list of the three numbers. (The first number is 0, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10508 second number is 1, and the third number is 2; this makes a total of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10509 three numbers in all, starting with zero as the first number.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10510 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10511 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10512 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10513 (let (value) ; otherwise a value is a void variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10514 (dotimes (number 3 value) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10515 (setq value (cons number value)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10516 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10517 @result{} (2 1 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10518 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10519 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10520 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10521 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10522 @code{dotimes} returns @code{value}, so the way to use |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10523 @code{dotimes} is to operate on some expression @var{number} number of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10524 times and then return the result, either as a list or an atom. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10525 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10526 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10527 Here is an example of a @code{defun} that uses @code{dotimes} to add |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10528 up the number of pebbles in a triangle. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10529 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10530 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10531 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10532 (defun triangle-using-dotimes (number-of-rows) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10533 "Using dotimes, add up the number of pebbles in a triangle." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10534 (let ((total 0)) ; otherwise a total is a void variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10535 (dotimes (number number-of-rows total) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10536 (setq total (+ total (1+ number)))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10537 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10538 (triangle-using-dotimes 4) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10539 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10540 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10541 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10542 @node Recursion, Looping exercise, dolist dotimes, Loops & Recursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10543 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10544 @section Recursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10545 @cindex Recursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10546 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10547 A recursive function contains code that tells the Lisp interpreter to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10548 call a program that runs exactly like itself, but with slightly |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10549 different arguments. The code runs exactly the same because it has |
45663
046819540e6d
Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents:
44899
diff
changeset
|
10550 the same name. However, even though the program has the same name, it |
046819540e6d
Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents:
44899
diff
changeset
|
10551 is not the same entity. It is different. In the jargon, it is a |
046819540e6d
Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents:
44899
diff
changeset
|
10552 different `instance'. |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10553 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10554 Eventually, if the program is written correctly, the `slightly |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10555 different arguments' will become sufficiently different from the first |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10556 arguments that the final instance will stop. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10557 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10558 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10559 * Building Robots:: Same model, different serial number ... |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10560 * Recursive Definition Parts:: Walk until you stop ... |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10561 * Recursion with list:: Using a list as the test whether to recurse. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10562 * Recursive triangle function:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10563 * Recursion with cond:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10564 * Recursive Patterns:: Often used templates. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10565 * No Deferment:: Don't store up work ... |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10566 * No deferment solution:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10567 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10568 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10569 @node Building Robots, Recursive Definition Parts, Recursion, Recursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10570 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10571 @subsection Building Robots: Extending the Metaphor |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10572 @cindex Building robots |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10573 @cindex Robots, building |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10574 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10575 It is sometimes helpful to think of a running program as a robot that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10576 does a job. In doing its job, a recursive function calls on a second |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10577 robot to help it. The second robot is identical to the first in every |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10578 way, except that the second robot helps the first and has been |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10579 passed different arguments than the first. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10580 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10581 In a recursive function, the second robot may call a third; and the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10582 third may call a fourth, and so on. Each of these is a different |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10583 entity; but all are clones. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10584 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10585 Since each robot has slightly different instructions---the arguments |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10586 will differ from one robot to the next---the last robot should know |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10587 when to stop. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10588 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10589 Let's expand on the metaphor in which a computer program is a robot. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10590 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10591 A function definition provides the blueprints for a robot. When you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10592 install a function definition, that is, when you evaluate a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10593 @code{defun} special form, you install the necessary equipment to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10594 build robots. It is as if you were in a factory, setting up an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10595 assembly line. Robots with the same name are built according to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10596 same blueprints. So they have, as it were, the same `model number', |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10597 but a different `serial number'. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10598 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10599 We often say that a recursive function `calls itself'. What we mean |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10600 is that the instructions in a recursive function cause the Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10601 interpreter to run a different function that has the same name and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10602 does the same job as the first, but with different arguments. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10603 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10604 It is important that the arguments differ from one instance to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10605 next; otherwise, the process will never stop. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10606 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10607 @node Recursive Definition Parts, Recursion with list, Building Robots, Recursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10608 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10609 @subsection The Parts of a Recursive Definition |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10610 @cindex Parts of a Recursive Definition |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10611 @cindex Recursive Definition Parts |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10612 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10613 A recursive function typically contains a conditional expression which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10614 has three parts: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10615 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10616 @enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10617 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10618 A true-or-false-test that determines whether the function is called |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10619 again, here called the @dfn{do-again-test}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10620 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10621 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10622 The name of the function. When this name is called, a new instance of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10623 the function---a new robot, as it were---is created and told what to do. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10624 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10625 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10626 An expression that returns a different value each time the function is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10627 called, here called the @dfn{next-step-expression}. Consequently, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10628 argument (or arguments) passed to the new instance of the function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10629 will be different from that passed to the previous instance. This |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10630 causes the conditional expression, the @dfn{do-again-test}, to test |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10631 false after the correct number of repetitions. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10632 @end enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10633 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10634 Recursive functions can be much simpler than any other kind of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10635 function. Indeed, when people first start to use them, they often look |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10636 so mysteriously simple as to be incomprehensible. Like riding a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10637 bicycle, reading a recursive function definition takes a certain knack |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10638 which is hard at first but then seems simple. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10639 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10640 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10641 There are several different common recursive patterns. A very simple |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10642 pattern looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10643 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10644 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10645 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10646 (defun @var{name-of-recursive-function} (@var{argument-list}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10647 "@var{documentation}@dots{}" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10648 (if @var{do-again-test} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10649 @var{body}@dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10650 (@var{name-of-recursive-function} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10651 @var{next-step-expression}))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10652 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10653 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10654 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10655 Each time a recursive function is evaluated, a new instance of it is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10656 created and told what to do. The arguments tell the instance what to do. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10657 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10658 An argument is bound to the value of the next-step-expression. Each |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10659 instance runs with a different value of the next-step-expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10660 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10661 The value in the next-step-expression is used in the do-again-test. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10662 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10663 The value returned by the next-step-expression is passed to the new |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10664 instance of the function, which evaluates it (or some |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10665 transmogrification of it) to determine whether to continue or stop. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10666 The next-step-expression is designed so that the do-again-test returns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10667 false when the function should no longer be repeated. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10668 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10669 The do-again-test is sometimes called the @dfn{stop condition}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10670 since it stops the repetitions when it tests false. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10671 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10672 @node Recursion with list, Recursive triangle function, Recursive Definition Parts, Recursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10673 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10674 @subsection Recursion with a List |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10675 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10676 The example of a @code{while} loop that printed the elements of a list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10677 of numbers can be written recursively. Here is the code, including |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10678 an expression to set the value of the variable @code{animals} to a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10679 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10680 If you are using Emacs 20 or before, this example must be copied to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10681 the @file{*scratch*} buffer and each expression must be evaluated |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10682 there. Use @kbd{C-u C-x C-e} to evaluate the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10683 @code{(print-elements-recursively animals)} expression so that the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10684 results are printed in the buffer; otherwise the Lisp interpreter will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10685 try to squeeze the results into the one line of the echo area. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10686 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10687 Also, place your cursor immediately after the last closing parenthesis |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10688 of the @code{print-elements-recursively} function, before the comment. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10689 Otherwise, the Lisp interpreter will try to evaluate the comment. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10690 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10691 If you are using Emacs 21 or later, you can evaluate this expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10692 directly in Info. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10693 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10694 @findex print-elements-recursively |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10695 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10696 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10697 (setq animals '(gazelle giraffe lion tiger)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10698 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10699 (defun print-elements-recursively (list) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10700 "Print each element of LIST on a line of its own. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10701 Uses recursion." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10702 (if list ; @r{do-again-test} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10703 (progn |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10704 (print (car list)) ; @r{body} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10705 (print-elements-recursively ; @r{recursive call} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10706 (cdr list))))) ; @r{next-step-expression} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10707 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10708 (print-elements-recursively animals) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10709 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10710 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10711 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10712 The @code{print-elements-recursively} function first tests whether |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10713 there is any content in the list; if there is, the function prints the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10714 first element of the list, the @sc{car} of the list. Then the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10715 function `invokes itself', but gives itself as its argument, not the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10716 whole list, but the second and subsequent elements of the list, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10717 @sc{cdr} of the list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10718 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10719 Put another way, if the list is not empty, the function invokes |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10720 another instance of code that is similar to the initial code, but is a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10721 different thread of execution, with different arguments than the first |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10722 instance. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10723 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10724 Put in yet another way, if the list is not empty, the first robot |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10725 assemblies a second robot and tells it what to do; the second robot is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10726 a different individual from the first, but is the same model. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10727 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10728 When the second evaluation occurs, the @code{if} expression is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10729 evaluated and if true, prints the first element of the list it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10730 receives as its argument (which is the second element of the original |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10731 list). Then the function `calls itself' with the @sc{cdr} of the list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10732 it is invoked with, which (the second time around) is the @sc{cdr} of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10733 the @sc{cdr} of the original list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10734 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10735 Note that although we say that the function `calls itself', what we |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10736 mean is that the Lisp interpreter assembles and instructs a new |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10737 instance of the program. The new instance is a clone of the first, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10738 but is a separate individual. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10739 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10740 Each time the function `invokes itself', it invokes itself on a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10741 shorter version of the original list. It creates a new instance that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10742 works on a shorter list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10743 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10744 Eventually, the function invokes itself on an empty list. It creates |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10745 a new instance whose argument is @code{nil}. The conditional expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10746 tests the value of @code{list}. Since the value of @code{list} is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10747 @code{nil}, the @code{if} expression tests false so the then-part is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10748 not evaluated. The function as a whole then returns @code{nil}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10749 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10750 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10751 When you evaluate @code{(print-elements-recursively animals)} in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10752 @file{*scratch*} buffer, you see this result: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10753 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10754 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10755 @group |
45663
046819540e6d
Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents:
44899
diff
changeset
|
10756 gazelle |
046819540e6d
Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents:
44899
diff
changeset
|
10757 |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10758 giraffe |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10759 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10760 lion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10761 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10762 tiger |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10763 nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10764 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10765 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10766 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10767 @node Recursive triangle function, Recursion with cond, Recursion with list, Recursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10768 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10769 @subsection Recursion in Place of a Counter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10770 @findex triangle-recursively |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10771 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10772 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10773 The @code{triangle} function described in a previous section can also |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10774 be written recursively. It looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10775 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10776 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10777 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10778 (defun triangle-recursively (number) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10779 "Return the sum of the numbers 1 through NUMBER inclusive. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10780 Uses recursion." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10781 (if (= number 1) ; @r{do-again-test} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10782 1 ; @r{then-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10783 (+ number ; @r{else-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10784 (triangle-recursively ; @r{recursive call} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10785 (1- number))))) ; @r{next-step-expression} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10786 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10787 (triangle-recursively 7) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10788 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10789 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10790 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10791 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10792 You can install this function by evaluating it and then try it by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10793 evaluating @code{(triangle-recursively 7)}. (Remember to put your |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10794 cursor immediately after the last parenthesis of the function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10795 definition, before the comment.) The function evaluates to 28. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10796 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10797 To understand how this function works, let's consider what happens in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10798 various cases when the function is passed 1, 2, 3, or 4 as the value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10799 its argument. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10801 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10802 * Recursive Example arg of 1 or 2:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10803 * Recursive Example arg of 3 or 4:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10804 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10805 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10806 @node Recursive Example arg of 1 or 2, Recursive Example arg of 3 or 4, Recursive triangle function, Recursive triangle function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10807 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10808 @unnumberedsubsubsec An argument of 1 or 2 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10809 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10810 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10811 First, what happens if the value of the argument is 1? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10812 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10813 The function has an @code{if} expression after the documentation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10814 string. It tests whether the value of @code{number} is equal to 1; if |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10815 so, Emacs evaluates the then-part of the @code{if} expression, which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10816 returns the number 1 as the value of the function. (A triangle with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10817 one row has one pebble in it.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10818 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10819 Suppose, however, that the value of the argument is 2. In this case, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10820 Emacs evaluates the else-part of the @code{if} expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10821 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10822 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10823 The else-part consists of an addition, the recursive call to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10824 @code{triangle-recursively} and a decrementing action; and it looks like |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10825 this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10826 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10827 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10828 (+ number (triangle-recursively (1- number))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10829 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10830 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10831 When Emacs evaluates this expression, the innermost expression is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10832 evaluated first; then the other parts in sequence. Here are the steps |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10833 in detail: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10834 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10835 @table @i |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10836 @item Step 1 @w{ } Evaluate the innermost expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10837 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10838 The innermost expression is @code{(1- number)} so Emacs decrements the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10839 value of @code{number} from 2 to 1. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10840 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10841 @item Step 2 @w{ } Evaluate the @code{triangle-recursively} function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10842 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10843 The Lisp interpreter creates an individual instance of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10844 @code{triangle-recursively}. It does not matter that this function is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10845 contained within itself. Emacs passes the result Step 1 as the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10846 argument used by this instance of the @code{triangle-recursively} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10847 function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10848 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10849 In this case, Emacs evaluates @code{triangle-recursively} with an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10850 argument of 1. This means that this evaluation of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10851 @code{triangle-recursively} returns 1. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10852 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10853 @item Step 3 @w{ } Evaluate the value of @code{number}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10854 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10855 The variable @code{number} is the second element of the list that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10856 starts with @code{+}; its value is 2. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10857 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10858 @item Step 4 @w{ } Evaluate the @code{+} expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10859 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10860 The @code{+} expression receives two arguments, the first |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10861 from the evaluation of @code{number} (Step 3) and the second from the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10862 evaluation of @code{triangle-recursively} (Step 2). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10863 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10864 The result of the addition is the sum of 2 plus 1, and the number 3 is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10865 returned, which is correct. A triangle with two rows has three |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10866 pebbles in it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10867 @end table |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10868 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10869 @node Recursive Example arg of 3 or 4, , Recursive Example arg of 1 or 2, Recursive triangle function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10870 @unnumberedsubsubsec An argument of 3 or 4 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10871 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10872 Suppose that @code{triangle-recursively} is called with an argument of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10873 3. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10874 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10875 @table @i |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10876 @item Step 1 @w{ } Evaluate the do-again-test. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10877 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10878 The @code{if} expression is evaluated first. This is the do-again |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10879 test and returns false, so the else-part of the @code{if} expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10880 is evaluated. (Note that in this example, the do-again-test causes |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10881 the function to call itself when it tests false, not when it tests |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10882 true.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10883 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10884 @item Step 2 @w{ } Evaluate the innermost expression of the else-part. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10885 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10886 The innermost expression of the else-part is evaluated, which decrements |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10887 3 to 2. This is the next-step-expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10888 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10889 @item Step 3 @w{ } Evaluate the @code{triangle-recursively} function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10890 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10891 The number 2 is passed to the @code{triangle-recursively} function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10892 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10893 We know what happens when Emacs evaluates @code{triangle-recursively} with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10894 an argument of 2. After going through the sequence of actions described |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10895 earlier, it returns a value of 3. So that is what will happen here. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10896 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10897 @item Step 4 @w{ } Evaluate the addition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10898 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10899 3 will be passed as an argument to the addition and will be added to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10900 number with which the function was called, which is 3. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10901 @end table |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10902 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10903 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10904 The value returned by the function as a whole will be 6. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10905 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10906 Now that we know what will happen when @code{triangle-recursively} is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10907 called with an argument of 3, it is evident what will happen if it is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10908 called with an argument of 4: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10909 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10910 @quotation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10911 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10912 In the recursive call, the evaluation of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10913 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10914 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10915 (triangle-recursively (1- 4)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10916 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10917 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10918 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10919 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10920 will return the value of evaluating |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10921 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10922 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10923 (triangle-recursively 3) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10924 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10925 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10926 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10927 which is 6 and this value will be added to 4 by the addition in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10928 third line. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10929 @end quotation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10930 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10931 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10932 The value returned by the function as a whole will be 10. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10933 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10934 Each time @code{triangle-recursively} is evaluated, it evaluates a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10935 version of itself---a different instance of itself---with a smaller |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10936 argument, until the argument is small enough so that it does not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10937 evaluate itself. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10938 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10939 Note that this particular design for a recursive function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10940 requires that operations be deferred. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10941 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10942 Before @code{(triangle-recursively 7)} can calculate its answer, it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10943 must call @code{(triangle-recursively 6)}; and before |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10944 @code{(triangle-recursively 6)} can calculate its answer, it must call |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10945 @code{(triangle-recursively 5)}; and so on. That is to say, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10946 calculation that @code{(triangle-recursively 7)} makes must be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10947 deferred until @code{(triangle-recursively 6)} makes its calculation; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10948 and @code{(triangle-recursively 6)} must defer until |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10949 @code{(triangle-recursively 5)} completes; and so on. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10950 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10951 If each of these instances of @code{triangle-recursively} are thought |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10952 of as different robots, the first robot must wait for the second to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10953 complete its job, which must wait until the third completes, and so |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10954 on. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10955 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10956 There is a way around this kind of waiting, which we will discuss in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10957 @ref{No Deferment, , Recursion without Deferments}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10958 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10959 @node Recursion with cond, Recursive Patterns, Recursive triangle function, Recursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10960 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10961 @subsection Recursion Example Using @code{cond} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10962 @findex cond |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10963 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10964 The version of @code{triangle-recursively} described earlier is written |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10965 with the @code{if} special form. It can also be written using another |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10966 special form called @code{cond}. The name of the special form |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10967 @code{cond} is an abbreviation of the word @samp{conditional}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10968 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10969 Although the @code{cond} special form is not used as often in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10970 Emacs Lisp sources as @code{if}, it is used often enough to justify |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10971 explaining it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10972 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10973 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10974 The template for a @code{cond} expression looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10975 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10976 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10977 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10978 (cond |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10979 @var{body}@dots{}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10980 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10981 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10982 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10983 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10984 where the @var{body} is a series of lists. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10985 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10986 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10987 Written out more fully, the template looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10988 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10989 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10990 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10991 (cond |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10992 (@var{first-true-or-false-test} @var{first-consequent}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10993 (@var{second-true-or-false-test} @var{second-consequent}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10994 (@var{third-true-or-false-test} @var{third-consequent}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10995 @dots{}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10996 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10997 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10998 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
10999 When the Lisp interpreter evaluates the @code{cond} expression, it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11000 evaluates the first element (the @sc{car} or true-or-false-test) of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11001 the first expression in a series of expressions within the body of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11002 @code{cond}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11003 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11004 If the true-or-false-test returns @code{nil} the rest of that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11005 expression, the consequent, is skipped and the true-or-false-test of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11006 next expression is evaluated. When an expression is found whose |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11007 true-or-false-test returns a value that is not @code{nil}, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11008 consequent of that expression is evaluated. The consequent can be one |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11009 or more expressions. If the consequent consists of more than one |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11010 expression, the expressions are evaluated in sequence and the value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11011 the last one is returned. If the expression does not have a consequent, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11012 the value of the true-or-false-test is returned. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11013 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11014 If none of the true-or-false-tests test true, the @code{cond} expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11015 returns @code{nil}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11016 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11017 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11018 Written using @code{cond}, the @code{triangle} function looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11019 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11020 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11021 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11022 (defun triangle-using-cond (number) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11023 (cond ((<= number 0) 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11024 ((= number 1) 1) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11025 ((> number 1) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11026 (+ number (triangle-using-cond (1- number)))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11027 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11028 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11029 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11030 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11031 In this example, the @code{cond} returns 0 if the number is less than or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11032 equal to 0, it returns 1 if the number is 1 and it evaluates @code{(+ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11033 number (triangle-using-cond (1- number)))} if the number is greater than |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11034 1. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11035 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11036 @node Recursive Patterns, No Deferment, Recursion with cond, Recursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11037 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11038 @subsection Recursive Patterns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11039 @cindex Recursive Patterns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11040 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11041 Here are three common recursive patterns. Each involves a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11042 Recursion does not need to involve lists, but Lisp is designed for lists |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11043 and this provides a sense of its primal capabilities. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11044 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11045 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11046 * Every:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11047 * Accumulate:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11048 * Keep:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11049 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11050 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11051 @node Every, Accumulate, Recursive Patterns, Recursive Patterns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11052 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11053 @unnumberedsubsubsec Recursive Pattern: @emph{every} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11054 @cindex Every, type of recursive pattern |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11055 @cindex Recursive pattern: every |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11056 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11057 In the @code{every} recursive pattern, an action is performed on every |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11058 element of a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11059 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11060 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11061 The basic pattern is: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11062 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11063 @itemize @bullet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11064 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11065 If a list be empty, return @code{nil}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11066 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11067 Else, act on the beginning of the list (the @sc{car} of the list) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11068 @itemize @minus |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11069 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11070 through a recursive call by the function on the rest (the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11071 @sc{cdr}) of the list, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11072 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11073 and, optionally, combine the acted-on element, using @code{cons}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11074 with the results of acting on the rest. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11075 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11076 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11077 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11078 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11079 Here is example: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11080 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11081 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11082 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11083 (defun square-each (numbers-list) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11084 "Square each of a NUMBERS LIST, recursively." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11085 (if (not numbers-list) ; do-again-test |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11086 nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11087 (cons |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11088 (* (car numbers-list) (car numbers-list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11089 (square-each (cdr numbers-list))))) ; next-step-expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11090 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11091 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11092 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11093 (square-each '(1 2 3)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11094 @result{} (1 4 9) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11095 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11096 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11097 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11098 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11099 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11100 If @code{numbers-list} is empty, do nothing. But if it has content, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11101 construct a list combining the square of the first number in the list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11102 with the result of the recursive call. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11103 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11104 (The example follows the pattern exactly: @code{nil} is returned if |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11105 the numbers' list is empty. In practice, you would write the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11106 conditional so it carries out the action when the numbers' list is not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11107 empty.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11108 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11109 The @code{print-elements-recursively} function (@pxref{Recursion with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11110 list, , Recursion with a List}) is another example of an @code{every} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11111 pattern, except in this case, rather than bring the results together |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11112 using @code{cons}, we print each element of output. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11113 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11114 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11115 The @code{print-elements-recursively} function looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11116 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11117 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11118 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11119 (setq animals '(gazelle giraffe lion tiger)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11120 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11121 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11122 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11123 (defun print-elements-recursively (list) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11124 "Print each element of LIST on a line of its own. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11125 Uses recursion." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11126 (if list ; @r{do-again-test} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11127 (progn |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11128 (print (car list)) ; @r{body} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11129 (print-elements-recursively ; @r{recursive call} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11130 (cdr list))))) ; @r{next-step-expression} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11131 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11132 (print-elements-recursively animals) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11133 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11134 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11135 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11136 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11137 The pattern for @code{print-elements-recursively} is: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11138 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11139 @itemize @bullet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11140 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11141 If the list be empty, do nothing. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11142 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11143 But if the list has at least one element, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11144 @itemize @minus |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11145 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11146 act on the beginning of the list (the @sc{car} of the list), |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11147 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11148 and make a recursive call on the rest (the @sc{cdr}) of the list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11149 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11150 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11151 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11152 @node Accumulate, Keep, Every, Recursive Patterns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11153 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11154 @unnumberedsubsubsec Recursive Pattern: @emph{accumulate} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11155 @cindex Accumulate, type of recursive pattern |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11156 @cindex Recursive pattern: accumulate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11157 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11158 Another recursive pattern is called the @code{accumulate} pattern. In |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11159 the @code{accumulate} recursive pattern, an action is performed on |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11160 every element of a list and the result of that action is accumulated |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11161 with the results of performing the action on the other elements. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11162 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11163 This is very like the `every' pattern using @code{cons}, except that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11164 @code{cons} is not used, but some other combiner. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11165 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11166 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11167 The pattern is: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11168 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11169 @itemize @bullet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11170 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11171 If a list be empty, return zero or some other constant. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11172 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11173 Else, act on the beginning of the list (the @sc{car} of the list), |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11174 @itemize @minus |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11175 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11176 and combine that acted-on element, using @code{+} or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11177 some other combining function, with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11178 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11179 a recursive call by the function on the rest (the @sc{cdr}) of the list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11180 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11181 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11182 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11183 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11184 Here is an example: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11185 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11186 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11187 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11188 (defun add-elements (numbers-list) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11189 "Add the elements of NUMBERS-LIST together." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11190 (if (not numbers-list) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11191 0 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11192 (+ (car numbers-list) (add-elements (cdr numbers-list))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11193 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11194 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11195 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11196 (add-elements '(1 2 3 4)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11197 @result{} 10 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11198 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11199 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11201 @xref{Files List, , Making a List of Files}, for an example of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11202 accumulate pattern. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11203 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11204 @node Keep, , Accumulate, Recursive Patterns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11205 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11206 @unnumberedsubsubsec Recursive Pattern: @emph{keep} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11207 @cindex Keep, type of recursive pattern |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11208 @cindex Recursive pattern: keep |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11209 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11210 A third recursive pattern is called the @code{keep} pattern. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11211 In the @code{keep} recursive pattern, each element of a list is tested; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11212 the element is acted on and the results are kept only if the element |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11213 meets a criterion. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11214 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11215 Again, this is very like the `every' pattern, except the element is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11216 skipped unless it meets a criterion. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11217 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11218 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11219 The pattern has three parts: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11220 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11221 @itemize @bullet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11222 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11223 If a list be empty, return @code{nil}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11224 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11225 Else, if the beginning of the list (the @sc{car} of the list) passes |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11226 a test |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11227 @itemize @minus |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11228 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11229 act on that element and combine it, using @code{cons} with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11230 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11231 a recursive call by the function on the rest (the @sc{cdr}) of the list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11232 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11233 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11234 Otherwise, if the beginning of the list (the @sc{car} of the list) fails |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11235 the test |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11236 @itemize @minus |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11237 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11238 skip on that element, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11239 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11240 and, recursively call the function on the rest (the @sc{cdr}) of the list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11241 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11242 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11243 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11244 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11245 Here is an example that uses @code{cond}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11246 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11247 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11248 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11249 (defun keep-three-letter-words (word-list) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11250 "Keep three letter words in WORD-LIST." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11251 (cond |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11252 ;; First do-again-test: stop-condition |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11253 ((not word-list) nil) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11254 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11255 ;; Second do-again-test: when to act |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11256 ((eq 3 (length (symbol-name (car word-list)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11257 ;; combine acted-on element with recursive call on shorter list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11258 (cons (car word-list) (keep-three-letter-words (cdr word-list)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11259 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11260 ;; Third do-again-test: when to skip element; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11261 ;; recursively call shorter list with next-step expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11262 (t (keep-three-letter-words (cdr word-list))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11263 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11264 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11265 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11266 (keep-three-letter-words '(one two three four five six)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11267 @result{} (one two six) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11268 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11269 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11270 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11271 It goes without saying that you need not use @code{nil} as the test for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11272 when to stop; and you can, of course, combine these patterns. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11273 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11274 @node No Deferment, No deferment solution, Recursive Patterns, Recursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11275 @subsection Recursion without Deferments |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11276 @cindex Deferment in recursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11277 @cindex Recursion without Deferments |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11278 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11279 Let's consider again what happens with the @code{triangle-recursively} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11280 function. We will find that the intermediate calculations are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11281 deferred until all can be done. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11282 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11283 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11284 Here is the function definition: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11285 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11286 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11287 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11288 (defun triangle-recursively (number) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11289 "Return the sum of the numbers 1 through NUMBER inclusive. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11290 Uses recursion." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11291 (if (= number 1) ; @r{do-again-test} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11292 1 ; @r{then-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11293 (+ number ; @r{else-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11294 (triangle-recursively ; @r{recursive call} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11295 (1- number))))) ; @r{next-step-expression} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11296 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11297 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11298 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11299 What happens when we call this function with a argument of 7? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11300 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11301 The first instance of the @code{triangle-recursively} function adds |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11302 the number 7 to the value returned by a second instance of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11303 @code{triangle-recursively}, an instance that has been passed an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11304 argument of 6. That is to say, the first calculation is: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11305 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11306 @smallexample |
45663
046819540e6d
Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents:
44899
diff
changeset
|
11307 (+ 7 (triangle-recursively 6)) |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11308 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11309 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11310 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11311 The first instance of @code{triangle-recursively}---you may want to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11312 think of it as a little robot---cannot complete its job. It must hand |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11313 off the calculation for @code{(triangle-recursively 6)} to a second |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11314 instance of the program, to a second robot. This second individual is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11315 completely different from the first one; it is, in the jargon, a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11316 `different instantiation'. Or, put another way, it is a different |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11317 robot. It is the same model as the first; it calculates triangle |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11318 numbers recursively; but it has a different serial number. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11319 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11320 And what does @code{(triangle-recursively 6)} return? It returns the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11321 number 6 added to the value returned by evaluating |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11322 @code{triangle-recursively} with an argument of 5. Using the robot |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11323 metaphor, it asks yet another robot to help it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11324 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11325 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11326 Now the total is: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11327 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11328 @smallexample |
45663
046819540e6d
Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents:
44899
diff
changeset
|
11329 (+ 7 6 (triangle-recursively 5)) |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11330 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11331 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11332 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11333 And what happens next? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11334 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11335 @smallexample |
45663
046819540e6d
Fix typos, clarify language.
Robert J. Chassell <bob@rattlesnake.com>
parents:
44899
diff
changeset
|
11336 (+ 7 6 5 (triangle-recursively 4)) |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11337 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11338 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11339 Each time @code{triangle-recursively} is called, except for the last |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11340 time, it creates another instance of the program---another robot---and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11341 asks it to make a calculation. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11342 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11343 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11344 Eventually, the full addition is set up and performed: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11345 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11346 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11347 (+ 7 6 5 4 3 2 1) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11348 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11349 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11350 This design for the function defers the calculation of the first step |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11351 until the second can be done, and defers that until the third can be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11352 done, and so on. Each deferment means the computer must remember what |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11353 is being waited on. This is not a problem when there are only a few |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11354 steps, as in this example. But it can be a problem when there are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11355 more steps. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11356 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11357 @node No deferment solution, , No Deferment, Recursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11358 @subsection No Deferment Solution |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11359 @cindex No deferment solution |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11360 @cindex Defermentless solution |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11361 @cindex Solution without deferment |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11362 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11363 The solution to the problem of deferred operations is to write in a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11364 manner that does not defer operations@footnote{The phrase @dfn{tail |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11365 recursive} is used to describe such a process, one that uses |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11366 `constant space'.}. This requires |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11367 writing to a different pattern, often one that involves writing two |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11368 function definitions, an `initialization' function and a `helper' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11369 function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11370 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11371 The `initialization' function sets up the job; the `helper' function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11372 does the work. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11373 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11374 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11375 Here are the two function definitions for adding up numbers. They are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11376 so simple, I find them hard to understand. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11377 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11378 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11379 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11380 (defun triangle-initialization (number) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11381 "Return the sum of the numbers 1 through NUMBER inclusive. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11382 This is the `initialization' component of a two function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11383 duo that uses recursion." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11384 (triangle-recursive-helper 0 0 number)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11385 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11386 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11387 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11388 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11389 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11390 (defun triangle-recursive-helper (sum counter number) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11391 "Return SUM, using COUNTER, through NUMBER inclusive. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11392 This is the `helper' component of a two function duo |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11393 that uses recursion." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11394 (if (> counter number) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11395 sum |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11396 (triangle-recursive-helper (+ sum counter) ; @r{sum} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11397 (1+ counter) ; @r{counter} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11398 number))) ; @r{number} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11399 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11400 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11401 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11402 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11403 Install both function definitions by evaluating them, then call |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11404 @code{triangle-initialization} with 2 rows: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11405 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11406 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11407 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11408 (triangle-initialization 2) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11409 @result{} 3 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11410 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11411 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11412 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11413 The `initialization' function calls the first instance of the `helper' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11414 function with three arguments: zero, zero, and a number which is the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11415 number of rows in the triangle. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11416 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11417 The first two arguments passed to the `helper' function are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11418 initialization values. These values are changed when |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11419 @code{triangle-recursive-helper} invokes new instances.@footnote{The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11420 jargon is mildly confusing: @code{triangle-recursive-helper} uses a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11421 process that is iterative in a procedure that is recursive. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11422 process is called iterative because the computer need only record the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11423 three values, @code{sum}, @code{counter}, and @code{number}; the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11424 procedure is recursive because the function `calls itself'. On the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11425 other hand, both the process and the procedure used by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11426 @code{triangle-recursively} are called recursive. The word |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11427 `recursive' has different meanings in the two contexts.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11428 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11429 Let's see what happens when we have a triangle that has one row. (This |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11430 triangle will have one pebble in it!) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11431 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11432 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11433 @code{triangle-initialization} will call its helper with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11434 the arguments @w{@code{0 0 1}}. That function will run the conditional |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11435 test whether @code{(> counter number)}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11436 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11437 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11438 (> 0 1) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11439 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11440 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11441 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11442 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11443 and find that the result is false, so it will invoke |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11444 the then-part of the @code{if} clause: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11445 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11446 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11447 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11448 (triangle-recursive-helper |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11449 (+ sum counter) ; @r{sum plus counter} @result{} @r{sum} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11450 (1+ counter) ; @r{increment counter} @result{} @r{counter} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11451 number) ; @r{number stays the same} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11452 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11453 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11454 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11455 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11456 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11457 which will first compute: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11458 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11459 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11460 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11461 (triangle-recursive-helper (+ 0 0) ; @r{sum} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11462 (1+ 0) ; @r{counter} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11463 1) ; @r{number} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11464 @exdent which is: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11465 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11466 (triangle-recursive-helper 0 1 1) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11467 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11468 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11469 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11470 Again, @code{(> counter number)} will be false, so again, the Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11471 interpreter will evaluate @code{triangle-recursive-helper}, creating a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11472 new instance with new arguments. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11473 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11474 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11475 This new instance will be; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11476 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11477 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11478 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11479 (triangle-recursive-helper |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11480 (+ sum counter) ; @r{sum plus counter} @result{} @r{sum} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11481 (1+ counter) ; @r{increment counter} @result{} @r{counter} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11482 number) ; @r{number stays the same} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11483 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11484 @exdent which is: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11485 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11486 (triangle-recursive-helper 1 2 1) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11487 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11488 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11489 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11490 In this case, the @code{(> counter number)} test will be true! So the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11491 instance will return the value of the sum, which will be 1, as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11492 expected. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11493 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11494 Now, let's pass @code{triangle-initialization} an argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11495 of 2, to find out how many pebbles there are in a triangle with two rows. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11496 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11497 That function calls @code{(triangle-recursive-helper 0 0 2)}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11498 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11499 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11500 In stages, the instances called will be: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11501 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11502 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11503 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11504 @r{sum counter number} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11505 (triangle-recursive-helper 0 1 2) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11506 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11507 (triangle-recursive-helper 1 2 2) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11508 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11509 (triangle-recursive-helper 3 3 2) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11510 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11511 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11512 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11513 When the last instance is called, the @code{(> counter number)} test |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11514 will be true, so the instance will return the value of @code{sum}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11515 which will be 3. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11516 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11517 This kind of pattern helps when you are writing functions that can use |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11518 many resources in a computer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11519 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11520 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11521 @node Looping exercise, , Recursion, Loops & Recursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11522 @section Looping Exercise |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11523 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11524 @itemize @bullet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11525 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11526 Write a function similar to @code{triangle} in which each row has a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11527 value which is the square of the row number. Use a @code{while} loop. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11528 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11529 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11530 Write a function similar to @code{triangle} that multiplies instead of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11531 adds the values. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11532 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11533 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11534 Rewrite these two functions recursively. Rewrite these functions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11535 using @code{cond}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11536 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11537 @c comma in printed title causes problem in Info cross reference |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11538 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11539 Write a function for Texinfo mode that creates an index entry at the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11540 beginning of a paragraph for every @samp{@@dfn} within the paragraph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11541 (In a Texinfo file, @samp{@@dfn} marks a definition. For more |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11542 information, see |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11543 @ifinfo |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11544 @ref{Indicating, , Indicating Definitions, texinfo}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11545 @end ifinfo |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11546 @ifhtml |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11547 @ref{Indicating, , Indicating, texinfo, Texinfo Manual}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11548 @end ifhtml |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11549 @iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11550 ``Indicating Definitions, Commands, etc.'' in @cite{Texinfo, The GNU |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11551 Documentation Format}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11552 @end iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11553 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11554 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11555 @node Regexp Search, Counting Words, Loops & Recursion, Top |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11556 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11557 @chapter Regular Expression Searches |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11558 @cindex Searches, illustrating |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11559 @cindex Regular expression searches |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11560 @cindex Patterns, searching for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11561 @cindex Motion by sentence and paragraph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11562 @cindex Sentences, movement by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11563 @cindex Paragraphs, movement by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11564 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11565 Regular expression searches are used extensively in GNU Emacs. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11566 two functions, @code{forward-sentence} and @code{forward-paragraph}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11567 illustrate these searches well. They use regular expressions to find |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11568 where to move point. The phrase `regular expression' is often written |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11569 as `regexp'. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11570 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11571 Regular expression searches are described in @ref{Regexp Search, , |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11572 Regular Expression Search, emacs, The GNU Emacs Manual}, as well as in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11573 @ref{Regular Expressions, , , elisp, The GNU Emacs Lisp Reference |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11574 Manual}. In writing this chapter, I am presuming that you have at |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11575 least a mild acquaintance with them. The major point to remember is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11576 that regular expressions permit you to search for patterns as well as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11577 for literal strings of characters. For example, the code in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11578 @code{forward-sentence} searches for the pattern of possible |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11579 characters that could mark the end of a sentence, and moves point to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11580 that spot. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11581 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11582 Before looking at the code for the @code{forward-sentence} function, it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11583 is worth considering what the pattern that marks the end of a sentence |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11584 must be. The pattern is discussed in the next section; following that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11585 is a description of the regular expression search function, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11586 @code{re-search-forward}. The @code{forward-sentence} function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11587 is described in the section following. Finally, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11588 @code{forward-paragraph} function is described in the last section of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11589 this chapter. @code{forward-paragraph} is a complex function that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11590 introduces several new features. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11591 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11592 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11593 * sentence-end:: The regular expression for @code{sentence-end}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11594 * re-search-forward:: Very similar to @code{search-forward}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11595 * forward-sentence:: A straightforward example of regexp search. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11596 * forward-paragraph:: A somewhat complex example. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11597 * etags:: How to create your own @file{TAGS} table. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11598 * Regexp Review:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11599 * re-search Exercises:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11600 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11601 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11602 @node sentence-end, re-search-forward, Regexp Search, Regexp Search |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11603 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11604 @section The Regular Expression for @code{sentence-end} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11605 @findex sentence-end |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11606 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11607 The symbol @code{sentence-end} is bound to the pattern that marks the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11608 end of a sentence. What should this regular expression be? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11609 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11610 Clearly, a sentence may be ended by a period, a question mark, or an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11611 exclamation mark. Indeed, only clauses that end with one of those three |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11612 characters should be considered the end of a sentence. This means that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11613 the pattern should include the character set: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11614 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11615 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11616 [.?!] |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11617 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11618 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11619 However, we do not want @code{forward-sentence} merely to jump to a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11620 period, a question mark, or an exclamation mark, because such a character |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11621 might be used in the middle of a sentence. A period, for example, is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11622 used after abbreviations. So other information is needed. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11623 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11624 According to convention, you type two spaces after every sentence, but |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11625 only one space after a period, a question mark, or an exclamation mark in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11626 the body of a sentence. So a period, a question mark, or an exclamation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11627 mark followed by two spaces is a good indicator of an end of sentence. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11628 However, in a file, the two spaces may instead be a tab or the end of a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11629 line. This means that the regular expression should include these three |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11630 items as alternatives. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11631 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11632 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11633 This group of alternatives will look like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11634 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11635 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11636 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11637 \\($\\| \\| \\) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11638 ^ ^^ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11639 TAB SPC |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11640 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11641 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11642 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11643 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11644 Here, @samp{$} indicates the end of the line, and I have pointed out |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11645 where the tab and two spaces are inserted in the expression. Both are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11646 inserted by putting the actual characters into the expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11647 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11648 Two backslashes, @samp{\\}, are required before the parentheses and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11649 vertical bars: the first backslash quotes the following backslash in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11650 Emacs; and the second indicates that the following character, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11651 parenthesis or the vertical bar, is special. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11652 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11653 @need 1000 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11654 Also, a sentence may be followed by one or more carriage returns, like |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11655 this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11656 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11657 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11658 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11659 [ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11660 ]* |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11661 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11662 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11663 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11664 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11665 Like tabs and spaces, a carriage return is inserted into a regular |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11666 expression by inserting it literally. The asterisk indicates that the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11667 @key{RET} is repeated zero or more times. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11668 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11669 But a sentence end does not consist only of a period, a question mark or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11670 an exclamation mark followed by appropriate space: a closing quotation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11671 mark or a closing brace of some kind may precede the space. Indeed more |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11672 than one such mark or brace may precede the space. These require a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11673 expression that looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11674 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11675 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11676 []\"')@}]* |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11677 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11678 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11679 In this expression, the first @samp{]} is the first character in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11680 expression; the second character is @samp{"}, which is preceded by a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11681 @samp{\} to tell Emacs the @samp{"} is @emph{not} special. The last |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11682 three characters are @samp{'}, @samp{)}, and @samp{@}}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11683 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11684 All this suggests what the regular expression pattern for matching the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11685 end of a sentence should be; and, indeed, if we evaluate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11686 @code{sentence-end} we find that it returns the following value: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11687 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11688 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11689 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11690 sentence-end |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11691 @result{} "[.?!][]\"')@}]*\\($\\| \\| \\)[ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11692 ]*" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11693 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11694 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11695 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11696 @ignore |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11697 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11698 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11699 (Note that here the @key{TAB}, two spaces, and @key{RET} are shown |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11700 literally in the pattern.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11701 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11702 This regular expression can be decyphered as follows: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11703 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11704 @table @code |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11705 @item [.?!] |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11706 The first part of the pattern is the three characters, a period, a question |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11707 mark and an exclamation mark, within square brackets. The pattern must |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11708 begin with one or other of these characters. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11709 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11710 @item []\"')@}]* |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11711 The second part of the pattern is the group of closing braces and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11712 quotation marks, which can appear zero or more times. These may follow |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11713 the period, question mark or exclamation mark. In a regular expression, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11714 the backslash, @samp{\}, followed by the double quotation mark, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11715 @samp{"}, indicates the class of string-quote characters. Usually, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11716 double quotation mark is the only character in this class. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11717 asterisk, @samp{*}, indicates that the items in the previous group (the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11718 group surrounded by square brackets, @samp{[]}) may be repeated zero or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11719 more times. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11720 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11721 @item \\($\\| \\| \\) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11722 The third part of the pattern is one or other of: either the end of a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11723 line, or two blank spaces, or a tab. The double back-slashes are used |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11724 to prevent Emacs from reading the parentheses and vertical bars as part |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11725 of the search pattern; the parentheses are used to mark the group and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11726 the vertical bars are used to indicated that the patterns to either side |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11727 of them are alternatives. The dollar sign is used to indicate the end |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11728 of a line and both the two spaces and the tab are each inserted as is to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11729 indicate what they are. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11730 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11731 @item [@key{RET}]* |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11732 Finally, the last part of the pattern indicates that the end of the line |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11733 or the whitespace following the period, question mark or exclamation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11734 mark may, but need not, be followed by one or more carriage returns. In |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11735 the pattern, the carriage return is inserted as an actual carriage |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11736 return between square brackets but here it is shown as @key{RET}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11737 @end table |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11738 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11739 @end ignore |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11740 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11741 @node re-search-forward, forward-sentence, sentence-end, Regexp Search |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11742 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11743 @section The @code{re-search-forward} Function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11744 @findex re-search-forward |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11745 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11746 The @code{re-search-forward} function is very like the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11747 @code{search-forward} function. (@xref{search-forward, , The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11748 @code{search-forward} Function}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11749 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11750 @code{re-search-forward} searches for a regular expression. If the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11751 search is successful, it leaves point immediately after the last |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11752 character in the target. If the search is backwards, it leaves point |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11753 just before the first character in the target. You may tell |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11754 @code{re-search-forward} to return @code{t} for true. (Moving point |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11755 is therefore a `side effect'.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11756 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11757 Like @code{search-forward}, the @code{re-search-forward} function takes |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11758 four arguments: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11759 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11760 @enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11761 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11762 The first argument is the regular expression that the function searches |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11763 for. The regular expression will be a string between quotations marks. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11764 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11765 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11766 The optional second argument limits how far the function will search; it is a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11767 bound, which is specified as a position in the buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11768 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11769 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11770 The optional third argument specifies how the function responds to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11771 failure: @code{nil} as the third argument causes the function to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11772 signal an error (and print a message) when the search fails; any other |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11773 value causes it to return @code{nil} if the search fails and @code{t} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11774 if the search succeeds. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11775 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11776 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11777 The optional fourth argument is the repeat count. A negative repeat |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11778 count causes @code{re-search-forward} to search backwards. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11779 @end enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11780 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11781 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11782 The template for @code{re-search-forward} looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11783 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11784 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11785 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11786 (re-search-forward "@var{regular-expression}" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11787 @var{limit-of-search} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11788 @var{what-to-do-if-search-fails} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11789 @var{repeat-count}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11790 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11791 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11792 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11793 The second, third, and fourth arguments are optional. However, if you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11794 want to pass a value to either or both of the last two arguments, you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11795 must also pass a value to all the preceding arguments. Otherwise, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11796 Lisp interpreter will mistake which argument you are passing the value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11797 to. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11798 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11799 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11800 In the @code{forward-sentence} function, the regular expression will be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11801 the value of the variable @code{sentence-end}, namely: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11802 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11803 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11804 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11805 "[.?!][]\"')@}]*\\($\\| \\| \\)[ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11806 ]*" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11807 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11808 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11809 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11810 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11811 The limit of the search will be the end of the paragraph (since a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11812 sentence cannot go beyond a paragraph). If the search fails, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11813 function will return @code{nil}; and the repeat count will be provided |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11814 by the argument to the @code{forward-sentence} function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11815 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11816 @node forward-sentence, forward-paragraph, re-search-forward, Regexp Search |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11817 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11818 @section @code{forward-sentence} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11819 @findex forward-sentence |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11820 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11821 The command to move the cursor forward a sentence is a straightforward |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11822 illustration of how to use regular expression searches in Emacs Lisp. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11823 Indeed, the function looks longer and more complicated than it is; this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11824 is because the function is designed to go backwards as well as forwards; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11825 and, optionally, over more than one sentence. The function is usually |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11826 bound to the key command @kbd{M-e}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11827 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11828 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11829 * Complete forward-sentence:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11830 * fwd-sentence while loops:: Two @code{while} loops. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11831 * fwd-sentence re-search:: A regular expression search. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11832 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11833 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11834 @node Complete forward-sentence, fwd-sentence while loops, forward-sentence, forward-sentence |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11835 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11836 @unnumberedsubsec Complete @code{forward-sentence} function definition |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11837 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11838 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11839 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11840 Here is the code for @code{forward-sentence}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11841 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11842 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11843 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11844 (defun forward-sentence (&optional arg) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11845 "Move forward to next sentence-end. With argument, repeat. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11846 With negative argument, move backward repeatedly to sentence-beginning. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11847 Sentence ends are identified by the value of sentence-end |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11848 treated as a regular expression. Also, every paragraph boundary |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11849 terminates sentences as well." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11850 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11851 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11852 (interactive "p") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11853 (or arg (setq arg 1)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11854 (while (< arg 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11855 (let ((par-beg |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11856 (save-excursion (start-of-paragraph-text) (point)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11857 (if (re-search-backward |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11858 (concat sentence-end "[^ \t\n]") par-beg t) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11859 (goto-char (1- (match-end 0))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11860 (goto-char par-beg))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11861 (setq arg (1+ arg))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11862 (while (> arg 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11863 (let ((par-end |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11864 (save-excursion (end-of-paragraph-text) (point)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11865 (if (re-search-forward sentence-end par-end t) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11866 (skip-chars-backward " \t\n") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11867 (goto-char par-end))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11868 (setq arg (1- arg)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11869 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11870 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11871 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11872 The function looks long at first sight and it is best to look at its |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11873 skeleton first, and then its muscle. The way to see the skeleton is to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11874 look at the expressions that start in the left-most columns: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11875 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11876 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11877 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11878 (defun forward-sentence (&optional arg) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11879 "@var{documentation}@dots{}" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11880 (interactive "p") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11881 (or arg (setq arg 1)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11882 (while (< arg 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11883 @var{body-of-while-loop} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11884 (while (> arg 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11885 @var{body-of-while-loop} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11886 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11887 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11888 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11889 This looks much simpler! The function definition consists of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11890 documentation, an @code{interactive} expression, an @code{or} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11891 expression, and @code{while} loops. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11892 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11893 Let's look at each of these parts in turn. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11894 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11895 We note that the documentation is thorough and understandable. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11896 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11897 The function has an @code{interactive "p"} declaration. This means |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11898 that the processed prefix argument, if any, is passed to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11899 function as its argument. (This will be a number.) If the function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11900 is not passed an argument (it is optional) then the argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11901 @code{arg} will be bound to 1. When @code{forward-sentence} is called |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11902 non-interactively without an argument, @code{arg} is bound to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11903 @code{nil}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11904 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11905 The @code{or} expression handles the prefix argument. What it does is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11906 either leave the value of @code{arg} as it is, but only if @code{arg} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11907 is bound to a value; or it sets the value of @code{arg} to 1, in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11908 case when @code{arg} is bound to @code{nil}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11909 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11910 @node fwd-sentence while loops, fwd-sentence re-search, Complete forward-sentence, forward-sentence |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11911 @unnumberedsubsec The @code{while} loops |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11912 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11913 Two @code{while} loops follow the @code{or} expression. The first |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11914 @code{while} has a true-or-false-test that tests true if the prefix |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11915 argument for @code{forward-sentence} is a negative number. This is for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11916 going backwards. The body of this loop is similar to the body of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11917 second @code{while} clause, but it is not exactly the same. We will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11918 skip this @code{while} loop and concentrate on the second @code{while} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11919 loop. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11920 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11921 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11922 The second @code{while} loop is for moving point forward. Its skeleton |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11923 looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11924 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11925 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11926 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11927 (while (> arg 0) ; @r{true-or-false-test} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11928 (let @var{varlist} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11929 (if (@var{true-or-false-test}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11930 @var{then-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11931 @var{else-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11932 (setq arg (1- arg)))) ; @code{while} @r{loop decrementer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11933 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11934 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11935 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11936 The @code{while} loop is of the decrementing kind. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11937 (@xref{Decrementing Loop, , A Loop with a Decrementing Counter}.) It |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11938 has a true-or-false-test that tests true so long as the counter (in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11939 this case, the variable @code{arg}) is greater than zero; and it has a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11940 decrementer that subtracts 1 from the value of the counter every time |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11941 the loop repeats. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11942 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11943 If no prefix argument is given to @code{forward-sentence}, which is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11944 the most common way the command is used, this @code{while} loop will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11945 run once, since the value of @code{arg} will be 1. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11946 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11947 The body of the @code{while} loop consists of a @code{let} expression, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11948 which creates and binds a local variable, and has, as its body, an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11949 @code{if} expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11950 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11951 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11952 The body of the @code{while} loop looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11953 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11954 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11955 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11956 (let ((par-end |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11957 (save-excursion (end-of-paragraph-text) (point)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11958 (if (re-search-forward sentence-end par-end t) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11959 (skip-chars-backward " \t\n") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11960 (goto-char par-end))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11961 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11962 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11963 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11964 The @code{let} expression creates and binds the local variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11965 @code{par-end}. As we shall see, this local variable is designed to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11966 provide a bound or limit to the regular expression search. If the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11967 search fails to find a proper sentence ending in the paragraph, it will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11968 stop on reaching the end of the paragraph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11969 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11970 But first, let us examine how @code{par-end} is bound to the value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11971 the end of the paragraph. What happens is that the @code{let} sets the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11972 value of @code{par-end} to the value returned when the Lisp interpreter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11973 evaluates the expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11974 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11975 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11976 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11977 (save-excursion (end-of-paragraph-text) (point)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11978 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11979 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11980 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11981 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11982 In this expression, @code{(end-of-paragraph-text)} moves point to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11983 end of the paragraph, @code{(point)} returns the value of point, and then |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11984 @code{save-excursion} restores point to its original position. Thus, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11985 the @code{let} binds @code{par-end} to the value returned by the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11986 @code{save-excursion} expression, which is the position of the end of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11987 the paragraph. (The @code{(end-of-paragraph-text)} function uses |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11988 @code{forward-paragraph}, which we will discuss shortly.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11989 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11990 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11991 Emacs next evaluates the body of the @code{let}, which is an @code{if} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11992 expression that looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11993 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11994 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11995 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11996 (if (re-search-forward sentence-end par-end t) ; @r{if-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11997 (skip-chars-backward " \t\n") ; @r{then-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11998 (goto-char par-end))) ; @r{else-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
11999 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12000 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12001 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12002 The @code{if} tests whether its first argument is true and if so, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12003 evaluates its then-part; otherwise, the Emacs Lisp interpreter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12004 evaluates the else-part. The true-or-false-test of the @code{if} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12005 expression is the regular expression search. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12006 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12007 It may seem odd to have what looks like the `real work' of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12008 the @code{forward-sentence} function buried here, but this is a common |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12009 way this kind of operation is carried out in Lisp. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12010 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12011 @node fwd-sentence re-search, , fwd-sentence while loops, forward-sentence |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12012 @unnumberedsubsec The regular expression search |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12013 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12014 The @code{re-search-forward} function searches for the end of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12015 sentence, that is, for the pattern defined by the @code{sentence-end} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12016 regular expression. If the pattern is found---if the end of the sentence is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12017 found---then the @code{re-search-forward} function does two things: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12018 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12019 @enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12020 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12021 The @code{re-search-forward} function carries out a side effect, which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12022 is to move point to the end of the occurrence found. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12023 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12024 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12025 The @code{re-search-forward} function returns a value of true. This is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12026 the value received by the @code{if}, and means that the search was |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12027 successful. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12028 @end enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12029 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12030 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12031 The side effect, the movement of point, is completed before the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12032 @code{if} function is handed the value returned by the successful |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12033 conclusion of the search. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12034 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12035 When the @code{if} function receives the value of true from a successful |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12036 call to @code{re-search-forward}, the @code{if} evaluates the then-part, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12037 which is the expression @code{(skip-chars-backward " \t\n")}. This |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12038 expression moves backwards over any blank spaces, tabs or carriage |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12039 returns until a printed character is found and then leaves point after |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12040 the character. Since point has already been moved to the end of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12041 pattern that marks the end of the sentence, this action leaves point |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12042 right after the closing printed character of the sentence, which is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12043 usually a period. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12044 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12045 On the other hand, if the @code{re-search-forward} function fails to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12046 find a pattern marking the end of the sentence, the function returns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12047 false. The false then causes the @code{if} to evaluate its third |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12048 argument, which is @code{(goto-char par-end)}: it moves point to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12049 end of the paragraph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12050 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12051 Regular expression searches are exceptionally useful and the pattern |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12052 illustrated by @code{re-search-forward}, in which the search is the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12053 test of an @code{if} expression, is handy. You will see or write code |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12054 incorporating this pattern often. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12055 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12056 @node forward-paragraph, etags, forward-sentence, Regexp Search |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12057 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12058 @section @code{forward-paragraph}: a Goldmine of Functions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12059 @findex forward-paragraph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12060 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12061 The @code{forward-paragraph} function moves point forward to the end |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12062 of the paragraph. It is usually bound to @kbd{M-@}} and makes use of a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12063 number of functions that are important in themselves, including |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12064 @code{let*}, @code{match-beginning}, and @code{looking-at}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12065 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12066 The function definition for @code{forward-paragraph} is considerably |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12067 longer than the function definition for @code{forward-sentence} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12068 because it works with a paragraph, each line of which may begin with a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12069 fill prefix. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12070 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12071 A fill prefix consists of a string of characters that are repeated at |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12072 the beginning of each line. For example, in Lisp code, it is a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12073 convention to start each line of a paragraph-long comment with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12074 @samp{;;; }. In Text mode, four blank spaces make up another common |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12075 fill prefix, creating an indented paragraph. (@xref{Fill Prefix, , , |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12076 emacs, The GNU Emacs Manual}, for more information about fill |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12077 prefixes.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12078 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12079 The existence of a fill prefix means that in addition to being able to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12080 find the end of a paragraph whose lines begin on the left-most |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12081 column, the @code{forward-paragraph} function must be able to find the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12082 end of a paragraph when all or many of the lines in the buffer begin |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12083 with the fill prefix. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12084 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12085 Moreover, it is sometimes practical to ignore a fill prefix that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12086 exists, especially when blank lines separate paragraphs. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12087 This is an added complication. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12088 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12089 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12090 * forward-paragraph in brief:: Key parts of the function definition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12091 * fwd-para let:: The @code{let*} expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12092 * fwd-para while:: The forward motion @code{while} loop. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12093 * fwd-para between paragraphs:: Movement between paragraphs. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12094 * fwd-para within paragraph:: Movement within paragraphs. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12095 * fwd-para no fill prefix:: When there is no fill prefix. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12096 * fwd-para with fill prefix:: When there is a fill prefix. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12097 * fwd-para summary:: Summary of @code{forward-paragraph} code. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12098 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12099 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12100 @node forward-paragraph in brief, fwd-para let, forward-paragraph, forward-paragraph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12101 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12102 @unnumberedsubsec Shortened @code{forward-paragraph} function definition |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12103 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12104 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12105 Rather than print all of the @code{forward-paragraph} function, we |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12106 will only print parts of it. Read without preparation, the function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12107 can be daunting! |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12108 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12109 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12110 In outline, the function looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12111 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12112 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12113 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12114 (defun forward-paragraph (&optional arg) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12115 "@var{documentation}@dots{}" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12116 (interactive "p") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12117 (or arg (setq arg 1)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12118 (let* |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12119 @var{varlist} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12120 (while (< arg 0) ; @r{backward-moving-code} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12121 @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12122 (setq arg (1+ arg))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12123 (while (> arg 0) ; @r{forward-moving-code} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12124 @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12125 (setq arg (1- arg))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12126 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12127 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12128 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12129 The first parts of the function are routine: the function's argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12130 list consists of one optional argument. Documentation follows. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12131 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12132 The lower case @samp{p} in the @code{interactive} declaration means |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12133 that the processed prefix argument, if any, is passed to the function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12134 This will be a number, and is the repeat count of how many paragraphs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12135 point will move. The @code{or} expression in the next line handles |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12136 the common case when no argument is passed to the function, which occurs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12137 if the function is called from other code rather than interactively. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12138 This case was described earlier. (@xref{forward-sentence, The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12139 @code{forward-sentence} function}.) Now we reach the end of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12140 familiar part of this function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12141 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12142 @node fwd-para let, fwd-para while, forward-paragraph in brief, forward-paragraph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12143 @unnumberedsubsec The @code{let*} expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12144 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12145 The next line of the @code{forward-paragraph} function begins a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12146 @code{let*} expression. This is a different kind of expression than |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12147 we have seen so far. The symbol is @code{let*} not @code{let}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12148 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12149 The @code{let*} special form is like @code{let} except that Emacs sets |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12150 each variable in sequence, one after another, and variables in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12151 latter part of the varlist can make use of the values to which Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12152 set variables in the earlier part of the varlist. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12153 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12154 In the @code{let*} expression in this function, Emacs binds two |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12155 variables: @code{fill-prefix-regexp} and @code{paragraph-separate}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12156 The value to which @code{paragraph-separate} is bound depends on the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12157 value of @code{fill-prefix-regexp}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12158 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12159 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12160 Let's look at each in turn. The symbol @code{fill-prefix-regexp} is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12161 set to the value returned by evaluating the following list: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12162 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12163 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12164 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12165 (and fill-prefix |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12166 (not (equal fill-prefix "")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12167 (not paragraph-ignore-fill-prefix) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12168 (regexp-quote fill-prefix)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12169 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12170 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12171 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12172 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12173 This is an expression whose first element is the @code{and} special form. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12174 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12175 As we learned earlier (@pxref{kill-new function, , The @code{kill-new} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12176 function}), the @code{and} special form evaluates each of its |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12177 arguments until one of the arguments returns a value of @code{nil}, in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12178 which case the @code{and} expression returns @code{nil}; however, if |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12179 none of the arguments returns a value of @code{nil}, the value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12180 resulting from evaluating the last argument is returned. (Since such |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12181 a value is not @code{nil}, it is considered true in Lisp.) In other |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12182 words, an @code{and} expression returns a true value only if all its |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12183 arguments are true. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12184 @findex and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12185 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12186 In this case, the variable @code{fill-prefix-regexp} is bound to a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12187 non-@code{nil} value only if the following four expressions produce a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12188 true (i.e., a non-@code{nil}) value when they are evaluated; otherwise, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12189 @code{fill-prefix-regexp} is bound to @code{nil}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12190 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12191 @table @code |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12192 @item fill-prefix |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12193 When this variable is evaluated, the value of the fill prefix, if any, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12194 is returned. If there is no fill prefix, this variable returns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12195 @code{nil}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12196 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12197 @item (not (equal fill-prefix "") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12198 This expression checks whether an existing fill prefix is an empty |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12199 string, that is, a string with no characters in it. An empty string is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12200 not a useful fill prefix. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12201 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12202 @item (not paragraph-ignore-fill-prefix) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12203 This expression returns @code{nil} if the variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12204 @code{paragraph-ignore-fill-prefix} has been turned on by being set to a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12205 true value such as @code{t}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12206 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12207 @item (regexp-quote fill-prefix) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12208 This is the last argument to the @code{and} special form. If all the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12209 arguments to the @code{and} are true, the value resulting from |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12210 evaluating this expression will be returned by the @code{and} expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12211 and bound to the variable @code{fill-prefix-regexp}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12212 @end table |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12213 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12214 @findex regexp-quote |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12215 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12216 The result of evaluating this @code{and} expression successfully is that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12217 @code{fill-prefix-regexp} will be bound to the value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12218 @code{fill-prefix} as modified by the @code{regexp-quote} function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12219 What @code{regexp-quote} does is read a string and return a regular |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12220 expression that will exactly match the string and match nothing else. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12221 This means that @code{fill-prefix-regexp} will be set to a value that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12222 will exactly match the fill prefix if the fill prefix exists. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12223 Otherwise, the variable will be set to @code{nil}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12224 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12225 The second local variable in the @code{let*} expression is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12226 @code{paragraph-separate}. It is bound to the value returned by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12227 evaluating the expression: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12228 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12229 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12230 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12231 (if fill-prefix-regexp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12232 (concat paragraph-separate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12233 "\\|^" fill-prefix-regexp "[ \t]*$") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12234 paragraph-separate))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12235 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12236 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12237 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12238 This expression shows why @code{let*} rather than @code{let} was used. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12239 The true-or-false-test for the @code{if} depends on whether the variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12240 @code{fill-prefix-regexp} evaluates to @code{nil} or some other value. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12241 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12242 If @code{fill-prefix-regexp} does not have a value, Emacs evaluates |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12243 the else-part of the @code{if} expression and binds |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12244 @code{paragraph-separate} to its local value. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12245 (@code{paragraph-separate} is a regular expression that matches what |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12246 separates paragraphs.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12247 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12248 But if @code{fill-prefix-regexp} does have a value, Emacs evaluates |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12249 the then-part of the @code{if} expression and binds |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12250 @code{paragraph-separate} to a regular expression that includes the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12251 @code{fill-prefix-regexp} as part of the pattern. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12252 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12253 Specifically, @code{paragraph-separate} is set to the original value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12254 of the paragraph separate regular expression concatenated with an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12255 alternative expression that consists of the @code{fill-prefix-regexp} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12256 followed by a blank line. The @samp{^} indicates that the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12257 @code{fill-prefix-regexp} must begin a line, and the optional |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12258 whitespace to the end of the line is defined by @w{@code{"[ \t]*$"}}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12259 The @samp{\\|} defines this portion of the regexp as an alternative to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12260 @code{paragraph-separate}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12261 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12262 Now we get into the body of the @code{let*}. The first part of the body |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12263 of the @code{let*} deals with the case when the function is given a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12264 negative argument and is therefore moving backwards. We will skip this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12265 section. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12266 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12267 @node fwd-para while, fwd-para between paragraphs, fwd-para let, forward-paragraph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12268 @unnumberedsubsec The forward motion @code{while} loop |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12269 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12270 The second part of the body of the @code{let*} deals with forward |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12271 motion. It is a @code{while} loop that repeats itself so long as the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12272 value of @code{arg} is greater than zero. In the most common use of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12273 the function, the value of the argument is 1, so the body of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12274 @code{while} loop is evaluated exactly once, and the cursor moves |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12275 forward one paragraph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12276 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12277 This part handles three situations: when point is between paragraphs, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12278 when point is within a paragraph and there is a fill prefix, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12279 when point is within a paragraph and there is no fill prefix. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12280 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12281 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12282 The @code{while} loop looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12283 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12284 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12285 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12286 (while (> arg 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12287 (beginning-of-line) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12288 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12289 ;; @r{between paragraphs} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12290 (while (prog1 (and (not (eobp)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12291 (looking-at paragraph-separate)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12292 (forward-line 1))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12293 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12294 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12295 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12296 ;; @r{within paragraphs, with a fill prefix} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12297 (if fill-prefix-regexp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12298 ;; @r{There is a fill prefix; it overrides paragraph-start.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12299 (while (and (not (eobp)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12300 (not (looking-at paragraph-separate)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12301 (looking-at fill-prefix-regexp)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12302 (forward-line 1)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12303 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12304 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12305 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12306 ;; @r{within paragraphs, no fill prefix} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12307 (if (re-search-forward paragraph-start nil t) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12308 (goto-char (match-beginning 0)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12309 (goto-char (point-max)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12310 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12311 (setq arg (1- arg))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12312 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12313 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12314 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12315 We can see immediately that this is a decrementing counter @code{while} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12316 loop, using the expression @code{(setq arg (1- arg))} as the decrementer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12317 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12318 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12319 The body of the loop consists of three expressions: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12320 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12321 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12322 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12323 ;; @r{between paragraphs} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12324 (beginning-of-line) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12325 (while |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12326 @var{body-of-while}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12327 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12328 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12329 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12330 ;; @r{within paragraphs, with fill prefix} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12331 (if @var{true-or-false-test} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12332 @var{then-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12333 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12334 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12335 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12336 ;; @r{within paragraphs, no fill prefix} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12337 @var{else-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12338 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12339 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12340 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12341 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12342 When the Emacs Lisp interpreter evaluates the body of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12343 @code{while} loop, the first thing it does is evaluate the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12344 @code{(beginning-of-line)} expression and move point to the beginning |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12345 of the line. Then there is an inner @code{while} loop. This |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12346 @code{while} loop is designed to move the cursor out of the blank |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12347 space between paragraphs, if it should happen to be there. Finally, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12348 there is an @code{if} expression that actually moves point to the end |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12349 of the paragraph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12350 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12351 @node fwd-para between paragraphs, fwd-para within paragraph, fwd-para while, forward-paragraph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12352 @unnumberedsubsec Between paragraphs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12353 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12354 First, let us look at the inner @code{while} loop. This loop handles |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12355 the case when point is between paragraphs; it uses three functions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12356 that are new to us: @code{prog1}, @code{eobp} and @code{looking-at}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12357 @findex prog1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12358 @findex eobp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12359 @findex looking-at |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12360 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12361 @itemize @bullet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12362 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12363 @code{prog1} is similar to the @code{progn} special form, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12364 except that @code{prog1} evaluates its arguments in sequence and then |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12365 returns the value of its first argument as the value of the whole |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12366 expression. (@code{progn} returns the value of its last argument as the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12367 value of the expression.) The second and subsequent arguments to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12368 @code{prog1} are evaluated only for their side effects. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12369 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12370 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12371 @code{eobp} is an abbreviation of @samp{End Of Buffer P} and is a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12372 function that returns true if point is at the end of the buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12373 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12374 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12375 @code{looking-at} is a function that returns true if the text following |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12376 point matches the regular expression passed @code{looking-at} as its |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12377 argument. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12378 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12379 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12380 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12381 The @code{while} loop we are studying looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12382 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12383 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12384 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12385 (while (prog1 (and (not (eobp)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12386 (looking-at paragraph-separate)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12387 (forward-line 1))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12388 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12389 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12390 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12391 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12392 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12393 This is a @code{while} loop with no body! The true-or-false-test of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12394 loop is the expression: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12395 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12396 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12397 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12398 (prog1 (and (not (eobp)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12399 (looking-at paragraph-separate)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12400 (forward-line 1)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12401 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12402 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12403 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12404 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12405 The first argument to the @code{prog1} is the @code{and} expression. It |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12406 has within in it a test of whether point is at the end of the buffer and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12407 also a test of whether the pattern following point matches the regular |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12408 expression for separating paragraphs. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12409 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12410 If the cursor is not at the end of the buffer and if the characters |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12411 following the cursor mark the separation between two paragraphs, then |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12412 the @code{and} expression is true. After evaluating the @code{and} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12413 expression, the Lisp interpreter evaluates the second argument to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12414 @code{prog1}, which is @code{forward-line}. This moves point forward |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12415 one line. The value returned by the @code{prog1} however, is the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12416 value of its first argument, so the @code{while} loop continues so |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12417 long as point is not at the end of the buffer and is between |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12418 paragraphs. When, finally, point is moved to a paragraph, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12419 @code{and} expression tests false. Note however, that the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12420 @code{forward-line} command is carried out anyhow. This means that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12421 when point is moved from between paragraphs to a paragraph, it is left |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12422 at the beginning of the second line of the paragraph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12423 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12424 @node fwd-para within paragraph, fwd-para no fill prefix, fwd-para between paragraphs, forward-paragraph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12425 @unnumberedsubsec Within paragraphs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12426 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12427 The next expression in the outer @code{while} loop is an @code{if} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12428 expression. The Lisp interpreter evaluates the then-part of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12429 @code{if} when the @code{fill-prefix-regexp} variable has a value other |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12430 than @code{nil}, and it evaluates the else-part when the value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12431 @code{if fill-prefix-regexp} is @code{nil}, that is, when there is no |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12432 fill prefix. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12433 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12434 @node fwd-para no fill prefix, fwd-para with fill prefix, fwd-para within paragraph, forward-paragraph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12435 @unnumberedsubsec No fill prefix |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12436 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12437 It is simplest to look at the code for the case when there is no fill |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12438 prefix first. This code consists of yet another inner @code{if} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12439 expression, and reads as follows: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12440 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12441 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12442 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12443 (if (re-search-forward paragraph-start nil t) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12444 (goto-char (match-beginning 0)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12445 (goto-char (point-max))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12446 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12447 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12448 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12449 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12450 This expression actually does the work that most people think of as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12451 the primary purpose of the @code{forward-paragraph} command: it causes |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12452 a regular expression search to occur that searches forward to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12453 start of the next paragraph and if it is found, moves point there; but |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12454 if the start of another paragraph if not found, it moves point to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12455 end of the accessible region of the buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12456 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12457 The only unfamiliar part of this is the use of @code{match-beginning}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12458 This is another function that is new to us. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12459 @code{match-beginning} function returns a number specifying the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12460 location of the start of the text that was matched by the last regular |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12461 expression search. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12462 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12463 The @code{match-beginning} function is used here because of a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12464 characteristic of a forward search: a successful forward search, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12465 regardless of whether it is a plain search or a regular expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12466 search, will move point to the end of the text that is found. In this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12467 case, a successful search will move point to the end of the pattern for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12468 @code{paragraph-start}, which will be the beginning of the next |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12469 paragraph rather than the end of the current one. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12470 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12471 However, we want to put point at the end of the current paragraph, not at |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12472 the beginning of the next one. The two positions may be different, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12473 because there may be several blank lines between paragraphs. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12474 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12475 @findex match-beginning |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12476 When given an argument of 0, @code{match-beginning} returns the position |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12477 that is the start of the text that the most recent regular |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12478 expression search matched. In this case, the most recent regular |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12479 expression search is the one looking for @code{paragraph-start}, so |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12480 @code{match-beginning} returns the beginning position of the pattern, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12481 rather than the end of the pattern. The beginning position is the end |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12482 of the paragraph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12483 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12484 (Incidentally, when passed a positive number as an argument, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12485 @code{match-beginning} function will place point at that parenthesized |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12486 expression in the last regular expression. It is a useful function.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12487 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12488 @node fwd-para with fill prefix, fwd-para summary, fwd-para no fill prefix, forward-paragraph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12489 @unnumberedsubsec With a fill prefix |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12490 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12491 The inner @code{if} expression just discussed is the else-part of an enclosing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12492 @code{if} expression which tests whether there is a fill prefix. If |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12493 there is a fill prefix, the then-part of this @code{if} is evaluated. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12494 It looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12495 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12496 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12497 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12498 (while (and (not (eobp)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12499 (not (looking-at paragraph-separate)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12500 (looking-at fill-prefix-regexp)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12501 (forward-line 1)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12502 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12503 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12504 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12505 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12506 What this expression does is move point forward line by line so long |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12507 as three conditions are true: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12508 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12509 @enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12510 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12511 Point is not at the end of the buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12512 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12513 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12514 The text following point does not separate paragraphs. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12515 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12516 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12517 The pattern following point is the fill prefix regular expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12518 @end enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12519 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12520 The last condition may be puzzling, until you remember that point was |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12521 moved to the beginning of the line early in the @code{forward-paragraph} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12522 function. This means that if the text has a fill prefix, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12523 @code{looking-at} function will see it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12524 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12525 @node fwd-para summary, , fwd-para with fill prefix, forward-paragraph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12526 @unnumberedsubsec Summary |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12527 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12528 In summary, when moving forward, the @code{forward-paragraph} function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12529 does the following: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12530 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12531 @itemize @bullet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12532 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12533 Move point to the beginning of the line. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12534 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12535 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12536 Skip over lines between paragraphs. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12537 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12538 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12539 Check whether there is a fill prefix, and if there is: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12540 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12541 @itemize --- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12542 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12543 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12544 Go forward line by line so long as the line is not a paragraph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12545 separating line. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12546 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12547 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12548 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12549 But if there is no fill prefix, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12550 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12551 @itemize --- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12552 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12553 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12554 Search for the next paragraph start pattern. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12555 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12556 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12557 Go to the beginning of the paragraph start pattern, which will be the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12558 end of the previous paragraph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12559 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12560 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12561 Or else go to the end of the accessible portion of the buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12562 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12563 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12564 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12565 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12566 For review, here is the code we have just been discussing, formatted |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12567 for clarity: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12568 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12569 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12570 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12571 (interactive "p") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12572 (or arg (setq arg 1)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12573 (let* ( |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12574 (fill-prefix-regexp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12575 (and fill-prefix (not (equal fill-prefix "")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12576 (not paragraph-ignore-fill-prefix) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12577 (regexp-quote fill-prefix))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12578 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12579 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12580 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12581 (paragraph-separate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12582 (if fill-prefix-regexp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12583 (concat paragraph-separate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12584 "\\|^" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12585 fill-prefix-regexp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12586 "[ \t]*$") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12587 paragraph-separate))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12588 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12589 @var{omitted-backward-moving-code} @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12590 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12591 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12592 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12593 (while (> arg 0) ; @r{forward-moving-code} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12594 (beginning-of-line) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12595 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12596 (while (prog1 (and (not (eobp)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12597 (looking-at paragraph-separate)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12598 (forward-line 1))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12599 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12600 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12601 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12602 (if fill-prefix-regexp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12603 (while (and (not (eobp)) ; @r{then-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12604 (not (looking-at paragraph-separate)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12605 (looking-at fill-prefix-regexp)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12606 (forward-line 1)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12607 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12608 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12609 ; @r{else-part: the inner-if} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12610 (if (re-search-forward paragraph-start nil t) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12611 (goto-char (match-beginning 0)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12612 (goto-char (point-max)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12613 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12614 (setq arg (1- arg))))) ; @r{decrementer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12615 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12616 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12617 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12618 The full definition for the @code{forward-paragraph} function not only |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12619 includes this code for going forwards, but also code for going backwards. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12620 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12621 If you are reading this inside of GNU Emacs and you want to see the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12622 whole function, you can type @kbd{C-h f} (@code{describe-function}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12623 and the name of the function. This gives you the function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12624 documentation and the name of the library containing the function's |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12625 source. Place point over the name of the library and press the RET |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12626 key; you will be taken directly to the source. (Be sure to install |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12627 your sources! Without them, you are like a person who tries to drive |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12628 a car with his eyes shut!) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12629 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12630 @c !!! again, 21.0.100 tags table location in this paragraph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12631 Or -- a good habit to get into -- you can type @kbd{M-.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12632 (@code{find-tag}) and the name of the function when prompted for it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12633 This will take you directly to the source. If the @code{find-tag} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12634 function first asks you for the name of a @file{TAGS} table, give it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12635 the name of the @file{TAGS} file such as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12636 @file{/usr/local/share/emacs/21.0.100/lisp/TAGS}. (The exact path to your |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12637 @file{TAGS} file depends on how your copy of Emacs was installed.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12638 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12639 You can also create your own @file{TAGS} file for directories that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12640 lack one. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12641 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12642 @xref{etags, , Create Your Own @file{TAGS} File}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12643 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12644 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12645 @node etags, Regexp Review, forward-paragraph, Regexp Search |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12646 @section Create Your Own @file{TAGS} File |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12647 @findex etags |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12648 @cindex @file{TAGS} file, create own |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12649 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12650 The @kbd{M-.} (@code{find-tag}) command takes you directly to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12651 source for a function, variable, node, or other source. The function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12652 depends on tags tables to tell it where to go. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12653 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12654 You often need to build and install tags tables yourself. They are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12655 not built automatically. A tags table is called a @file{TAGS} file; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12656 the name is in upper case letters. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12657 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12658 You can create a @file{TAGS} file by calling the @code{etags} program |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12659 that comes as a part of the Emacs distribution. Usually, @code{etags} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12660 is compiled and installed when Emacs is built. (@code{etags} is not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12661 an Emacs Lisp function or a part of Emacs; it is a C program.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12662 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12663 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12664 To create a @file{TAGS} file, first switch to the directory in which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12665 you want to create the file. In Emacs you can do this with the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12666 @kbd{M-x cd} command, or by visiting a file in the directory, or by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12667 listing the directory with @kbd{C-x d} (@code{dired}). Then run the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12668 compile command, with @w{@code{etags *.el}} as the command to execute |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12669 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12670 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12671 M-x compile RET etags *.el RET |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12672 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12673 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12674 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12675 to create a @file{TAGS} file. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12676 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12677 For example, if you have a large number of files in your |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12678 @file{~/emacs} directory, as I do---I have 137 @file{.el} files in it, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12679 of which I load 12---you can create a @file{TAGS} file for the Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12680 Lisp files in that directory. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12681 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12682 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12683 The @code{etags} program takes all the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12684 usual shell `wildcards'. For example, if you have two directories for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12685 which you want a single @file{TAGS file}, type |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12686 @w{@code{etags *.el ../elisp/*.el}}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12687 where @file{../elisp/} is the second directory: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12688 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12689 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12690 M-x compile RET etags *.el ../elisp/*.el RET |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12691 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12692 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12693 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12694 Type |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12695 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12696 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12697 M-x compile RET etags --help RET |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12698 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12699 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12700 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12701 to see a list of the options accepted by @code{etags} as well as a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12702 list of supported languages. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12703 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12704 The @code{etags} program handles more than 20 languages, including |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12705 Emacs Lisp, Common Lisp, Scheme, C, C++, Ada, Fortran, Java, LaTeX, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12706 Pascal, Perl, Python, Texinfo, makefiles, and most assemblers. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12707 program has no switches for specifying the language; it recognizes the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12708 language in an input file according to its file name and contents. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12709 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12710 @file{etags} is very helpful when you are writing code yourself and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12711 want to refer back to functions you have already written. Just run |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12712 @code{etags} again at intervals as you write new functions, so they |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12713 become part of the @file{TAGS} file. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12714 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12715 If you think an appropriate @file{TAGS} file already exists for what |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12716 you want, but do not know where it is, you can use the @code{locate} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12717 program to attempt to find it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12718 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12719 Type @w{@kbd{M-x locate RET TAGS RET}} and Emacs will list for you the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12720 full path names of all your @file{TAGS} files. On my system, this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12721 command lists 34 @file{TAGS} files. On the other hand, a `plain |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12722 vanilla' system I recently installed did not contain any @file{TAGS} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12723 files. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12724 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12725 If the tags table you want has been created, you can use the @code{M-x |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12726 visit-tags-table} command to specify it. Otherwise, you will need to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12727 create the tag table yourself and then use @code{M-x |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12728 visit-tags-table}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12729 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12730 @subsubheading Building Tags in the Emacs sources |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12731 @cindex Building Tags in the Emacs sources |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12732 @cindex Tags in the Emacs sources |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12733 @findex make tags |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12734 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12735 The GNU Emacs sources come with a @file{Makefile} that contains a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12736 sophisticated @code{etags} command that creates, collects, and merges |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12737 tags tables from all over the Emacs sources and puts the information |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12738 into one @file{TAGS} file in the @file{src/} directory below the top |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12739 level of your Emacs source directory. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12740 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12741 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12742 To build this @file{TAGS} file, go to the top level of your Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12743 source directory and run the compile command @code{make tags}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12744 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12745 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12746 M-x compile RET make tags RET |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12747 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12748 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12749 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12750 (The @code{make tags} command works well with the GNU Emacs sources, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12751 as well as with some other source packages.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12752 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12753 For more information, see @ref{Tags, , Tag Tables, emacs, The GNU Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12754 Manual}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12755 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12756 @node Regexp Review, re-search Exercises, etags, Regexp Search |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12757 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12758 @section Review |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12759 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12760 Here is a brief summary of some recently introduced functions. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12761 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12762 @table @code |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12763 @item while |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12764 Repeatedly evaluate the body of the expression so long as the first |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12765 element of the body tests true. Then return @code{nil}. (The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12766 expression is evaluated only for its side effects.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12767 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12768 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12769 For example: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12770 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12771 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12772 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12773 (let ((foo 2)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12774 (while (> foo 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12775 (insert (format "foo is %d.\n" foo)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12776 (setq foo (1- foo)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12777 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12778 @result{} foo is 2. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12779 foo is 1. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12780 nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12781 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12782 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12783 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12784 (The @code{insert} function inserts its arguments at point; the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12785 @code{format} function returns a string formatted from its arguments |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12786 the way @code{message} formats its arguments; @code{\n} produces a new |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12787 line.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12788 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12789 @item re-search-forward |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12790 Search for a pattern, and if the pattern is found, move point to rest |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12791 just after it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12792 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12793 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12794 Takes four arguments, like @code{search-forward}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12795 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12796 @enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12797 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12798 A regular expression that specifies the pattern to search for. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12799 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12800 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12801 Optionally, the limit of the search. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12802 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12803 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12804 Optionally, what to do if the search fails, return @code{nil} or an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12805 error message. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12806 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12807 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12808 Optionally, how many times to repeat the search; if negative, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12809 search goes backwards. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12810 @end enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12811 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12812 @item let* |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12813 Bind some variables locally to particular values, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12814 and then evaluate the remaining arguments, returning the value of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12815 last one. While binding the local variables, use the local values of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12816 variables bound earlier, if any. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12817 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12818 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12819 For example: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12820 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12821 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12822 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12823 (let* ((foo 7) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12824 (bar (* 3 foo))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12825 (message "`bar' is %d." bar)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12826 @result{} `bar' is 21. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12827 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12828 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12829 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12830 @item match-beginning |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12831 Return the position of the start of the text found by the last regular |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12832 expression search. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12833 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12834 @item looking-at |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12835 Return @code{t} for true if the text after point matches the argument, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12836 which should be a regular expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12837 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12838 @item eobp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12839 Return @code{t} for true if point is at the end of the accessible part |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12840 of a buffer. The end of the accessible part is the end of the buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12841 if the buffer is not narrowed; it is the end of the narrowed part if |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12842 the buffer is narrowed. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12843 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12844 @item prog1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12845 Evaluate each argument in sequence and then return the value of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12846 @emph{first}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12847 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12848 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12849 For example: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12850 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12851 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12852 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12853 (prog1 1 2 3 4) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12854 @result{} 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12855 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12856 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12857 @end table |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12858 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12859 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12860 @node re-search Exercises, , Regexp Review, Regexp Search |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12861 @section Exercises with @code{re-search-forward} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12862 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12863 @itemize @bullet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12864 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12865 Write a function to search for a regular expression that matches two |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12866 or more blank lines in sequence. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12867 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12868 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12869 Write a function to search for duplicated words, such as `the the'. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12870 @xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12871 Manual}, for information on how to write a regexp (a regular |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12872 expression) to match a string that is composed of two identical |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12873 halves. You can devise several regexps; some are better than others. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12874 The function I use is described in an appendix, along with several |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12875 regexps. @xref{the-the, , @code{the-the} Duplicated Words Function}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12876 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12877 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12878 @node Counting Words, Words in a defun, Regexp Search, Top |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12879 @chapter Counting: Repetition and Regexps |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12880 @cindex Repetition for word counting |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12881 @cindex Regular expressions for word counting |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12882 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12883 Repetition and regular expression searches are powerful tools that you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12884 often use when you write code in Emacs Lisp. This chapter illustrates |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12885 the use of regular expression searches through the construction of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12886 word count commands using @code{while} loops and recursion. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12887 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12888 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12889 * Why Count Words:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12890 * count-words-region:: Use a regexp, but find a problem. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12891 * recursive-count-words:: Start with case of no words in region. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12892 * Counting Exercise:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12893 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12894 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12895 @node Why Count Words, count-words-region, Counting Words, Counting Words |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12896 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12897 @unnumberedsec Counting words |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12898 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12899 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12900 The standard Emacs distribution contains a function for counting the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12901 number of lines within a region. However, there is no corresponding |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12902 function for counting words. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12903 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12904 Certain types of writing ask you to count words. Thus, if you write |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12905 an essay, you may be limited to 800 words; if you write a novel, you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12906 may discipline yourself to write 1000 words a day. It seems odd to me |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12907 that Emacs lacks a word count command. Perhaps people use Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12908 mostly for code or types of documentation that do not require word |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12909 counts; or perhaps they restrict themselves to the operating system |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12910 word count command, @code{wc}. Alternatively, people may follow |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12911 the publishers' convention and compute a word count by dividing the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12912 number of characters in a document by five. In any event, here are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12913 commands to count words. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12914 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12915 @node count-words-region, recursive-count-words, Why Count Words, Counting Words |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12916 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12917 @section The @code{count-words-region} Function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12918 @findex count-words-region |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12919 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12920 A word count command could count words in a line, paragraph, region, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12921 or buffer. What should the command cover? You could design the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12922 command to count the number of words in a complete buffer. However, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12923 the Emacs tradition encourages flexibility---you may want to count |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12924 words in just a section, rather than all of a buffer. So it makes |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12925 more sense to design the command to count the number of words in a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12926 region. Once you have a @code{count-words-region} command, you can, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12927 if you wish, count words in a whole buffer by marking it with @kbd{C-x |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12928 h} (@code{mark-whole-buffer}). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12929 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12930 Clearly, counting words is a repetitive act: starting from the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12931 beginning of the region, you count the first word, then the second |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12932 word, then the third word, and so on, until you reach the end of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12933 region. This means that word counting is ideally suited to recursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12934 or to a @code{while} loop. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12935 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12936 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12937 * Design count-words-region:: The definition using a @code{while} loop. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12938 * Whitespace Bug:: The Whitespace Bug in @code{count-words-region}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12939 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12940 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12941 @node Design count-words-region, Whitespace Bug, count-words-region, count-words-region |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12942 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12943 @unnumberedsubsec Designing @code{count-words-region} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12944 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12945 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12946 First, we will implement the word count command with a @code{while} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12947 loop, then with recursion. The command will, of course, be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12948 interactive. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12949 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12950 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12951 The template for an interactive function definition is, as always: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12952 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12953 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12954 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12955 (defun @var{name-of-function} (@var{argument-list}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12956 "@var{documentation}@dots{}" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12957 (@var{interactive-expression}@dots{}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12958 @var{body}@dots{}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12959 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12960 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12961 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12962 What we need to do is fill in the slots. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12963 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12964 The name of the function should be self-explanatory and similar to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12965 existing @code{count-lines-region} name. This makes the name easier |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12966 to remember. @code{count-words-region} is a good choice. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12967 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12968 The function counts words within a region. This means that the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12969 argument list must contain symbols that are bound to the two |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12970 positions, the beginning and end of the region. These two positions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12971 can be called @samp{beginning} and @samp{end} respectively. The first |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12972 line of the documentation should be a single sentence, since that is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12973 all that is printed as documentation by a command such as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12974 @code{apropos}. The interactive expression will be of the form |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12975 @samp{(interactive "r")}, since that will cause Emacs to pass the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12976 beginning and end of the region to the function's argument list. All |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12977 this is routine. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12978 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12979 The body of the function needs to be written to do three tasks: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12980 first, to set up conditions under which the @code{while} loop can |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12981 count words, second, to run the @code{while} loop, and third, to send |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12982 a message to the user. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12983 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12984 When a user calls @code{count-words-region}, point may be at the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12985 beginning or the end of the region. However, the counting process |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12986 must start at the beginning of the region. This means we will want |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12987 to put point there if it is not already there. Executing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12988 @code{(goto-char beginning)} ensures this. Of course, we will want to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12989 return point to its expected position when the function finishes its |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12990 work. For this reason, the body must be enclosed in a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12991 @code{save-excursion} expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12992 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12993 The central part of the body of the function consists of a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12994 @code{while} loop in which one expression jumps point forward word by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12995 word, and another expression counts those jumps. The true-or-false-test |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12996 of the @code{while} loop should test true so long as point should jump |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12997 forward, and false when point is at the end of the region. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12998 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
12999 We could use @code{(forward-word 1)} as the expression for moving point |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13000 forward word by word, but it is easier to see what Emacs identifies as a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13001 `word' if we use a regular expression search. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13002 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13003 A regular expression search that finds the pattern for which it is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13004 searching leaves point after the last character matched. This means |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13005 that a succession of successful word searches will move point forward |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13006 word by word. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13007 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13008 As a practical matter, we want the regular expression search to jump |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13009 over whitespace and punctuation between words as well as over the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13010 words themselves. A regexp that refuses to jump over interword |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13011 whitespace would never jump more than one word! This means that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13012 the regexp should include the whitespace and punctuation that follows |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13013 a word, if any, as well as the word itself. (A word may end a buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13014 and not have any following whitespace or punctuation, so that part of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13015 the regexp must be optional.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13016 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13017 Thus, what we want for the regexp is a pattern defining one or more |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13018 word constituent characters followed, optionally, by one or more |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13019 characters that are not word constituents. The regular expression for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13020 this is: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13021 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13022 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13023 \w+\W* |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13024 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13025 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13026 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13027 The buffer's syntax table determines which characters are and are not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13028 word constituents. (@xref{Syntax, , What Constitutes a Word or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13029 Symbol?}, for more about syntax. Also, see @ref{Syntax, Syntax, The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13030 Syntax Table, emacs, The GNU Emacs Manual}, and @ref{Syntax Tables, , |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13031 Syntax Tables, elisp, The GNU Emacs Lisp Reference Manual}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13032 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13033 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13034 The search expression looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13035 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13036 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13037 (re-search-forward "\\w+\\W*") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13038 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13039 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13040 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13041 (Note that paired backslashes precede the @samp{w} and @samp{W}. A |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13042 single backslash has special meaning to the Emacs Lisp interpreter. It |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13043 indicates that the following character is interpreted differently than |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13044 usual. For example, the two characters, @samp{\n}, stand for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13045 @samp{newline}, rather than for a backslash followed by @samp{n}. Two |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13046 backslashes in a row stand for an ordinary, `unspecial' backslash.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13047 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13048 We need a counter to count how many words there are; this variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13049 must first be set to 0 and then incremented each time Emacs goes |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13050 around the @code{while} loop. The incrementing expression is simply: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13051 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13052 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13053 (setq count (1+ count)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13054 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13055 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13056 Finally, we want to tell the user how many words there are in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13057 region. The @code{message} function is intended for presenting this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13058 kind of information to the user. The message has to be phrased so |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13059 that it reads properly regardless of how many words there are in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13060 region: we don't want to say that ``there are 1 words in the region''. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13061 The conflict between singular and plural is ungrammatical. We can |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13062 solve this problem by using a conditional expression that evaluates |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13063 different messages depending on the number of words in the region. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13064 There are three possibilities: no words in the region, one word in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13065 region, and more than one word. This means that the @code{cond} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13066 special form is appropriate. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13067 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13068 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13069 All this leads to the following function definition: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13070 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13071 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13072 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13073 ;;; @r{First version; has bugs!} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13074 (defun count-words-region (beginning end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13075 "Print number of words in the region. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13076 Words are defined as at least one word-constituent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13077 character followed by at least one character that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13078 is not a word-constituent. The buffer's syntax |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13079 table determines which characters these are." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13080 (interactive "r") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13081 (message "Counting words in region ... ") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13082 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13083 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13084 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13085 ;;; @r{1. Set up appropriate conditions.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13086 (save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13087 (goto-char beginning) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13088 (let ((count 0)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13089 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13090 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13091 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13092 ;;; @r{2. Run the} while @r{loop.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13093 (while (< (point) end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13094 (re-search-forward "\\w+\\W*") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13095 (setq count (1+ count))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13096 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13097 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13098 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13099 ;;; @r{3. Send a message to the user.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13100 (cond ((zerop count) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13101 (message |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13102 "The region does NOT have any words.")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13103 ((= 1 count) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13104 (message |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13105 "The region has 1 word.")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13106 (t |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13107 (message |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13108 "The region has %d words." count)))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13109 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13110 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13111 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13112 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13113 As written, the function works, but not in all circumstances. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13114 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13115 @node Whitespace Bug, , Design count-words-region, count-words-region |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13116 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13117 @subsection The Whitespace Bug in @code{count-words-region} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13118 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13119 The @code{count-words-region} command described in the preceding |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13120 section has two bugs, or rather, one bug with two manifestations. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13121 First, if you mark a region containing only whitespace in the middle |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13122 of some text, the @code{count-words-region} command tells you that the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13123 region contains one word! Second, if you mark a region containing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13124 only whitespace at the end of the buffer or the accessible portion of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13125 a narrowed buffer, the command displays an error message that looks |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13126 like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13127 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13128 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13129 Search failed: "\\w+\\W*" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13130 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13131 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13132 If you are reading this in Info in GNU Emacs, you can test for these |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13133 bugs yourself. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13134 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13135 First, evaluate the function in the usual manner to install it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13136 @ifinfo |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13137 Here is a copy of the definition. Place your cursor after the closing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13138 parenthesis and type @kbd{C-x C-e} to install it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13139 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13140 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13141 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13142 ;; @r{First version; has bugs!} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13143 (defun count-words-region (beginning end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13144 "Print number of words in the region. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13145 Words are defined as at least one word-constituent character followed |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13146 by at least one character that is not a word-constituent. The buffer's |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13147 syntax table determines which characters these are." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13148 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13149 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13150 (interactive "r") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13151 (message "Counting words in region ... ") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13152 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13153 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13154 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13155 ;;; @r{1. Set up appropriate conditions.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13156 (save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13157 (goto-char beginning) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13158 (let ((count 0)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13159 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13160 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13161 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13162 ;;; @r{2. Run the} while @r{loop.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13163 (while (< (point) end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13164 (re-search-forward "\\w+\\W*") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13165 (setq count (1+ count))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13166 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13167 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13168 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13169 ;;; @r{3. Send a message to the user.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13170 (cond ((zerop count) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13171 (message "The region does NOT have any words.")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13172 ((= 1 count) (message "The region has 1 word.")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13173 (t (message "The region has %d words." count)))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13174 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13175 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13176 @end ifinfo |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13177 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13178 @need 1000 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13179 If you wish, you can also install this keybinding by evaluating it: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13180 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13181 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13182 (global-set-key "\C-c=" 'count-words-region) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13183 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13184 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13185 To conduct the first test, set mark and point to the beginning and end |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13186 of the following line and then type @kbd{C-c =} (or @kbd{M-x |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13187 count-words-region} if you have not bound @kbd{C-c =}): |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13188 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13189 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13190 one two three |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13191 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13192 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13193 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13194 Emacs will tell you, correctly, that the region has three words. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13195 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13196 Repeat the test, but place mark at the beginning of the line and place |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13197 point just @emph{before} the word @samp{one}. Again type the command |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13198 @kbd{C-c =} (or @kbd{M-x count-words-region}). Emacs should tell you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13199 that the region has no words, since it is composed only of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13200 whitespace at the beginning of the line. But instead Emacs tells you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13201 that the region has one word! |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13202 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13203 For the third test, copy the sample line to the end of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13204 @file{*scratch*} buffer and then type several spaces at the end of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13205 line. Place mark right after the word @samp{three} and point at the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13206 end of line. (The end of the line will be the end of the buffer.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13207 Type @kbd{C-c =} (or @kbd{M-x count-words-region}) as you did before. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13208 Again, Emacs should tell you that the region has no words, since it is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13209 composed only of the whitespace at the end of the line. Instead, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13210 Emacs displays an error message saying @samp{Search failed}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13211 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13212 The two bugs stem from the same problem. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13213 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13214 Consider the first manifestation of the bug, in which the command |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13215 tells you that the whitespace at the beginning of the line contains |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13216 one word. What happens is this: The @code{M-x count-words-region} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13217 command moves point to the beginning of the region. The @code{while} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13218 tests whether the value of point is smaller than the value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13219 @code{end}, which it is. Consequently, the regular expression search |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13220 looks for and finds the first word. It leaves point after the word. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13221 @code{count} is set to one. The @code{while} loop repeats; but this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13222 time the value of point is larger than the value of @code{end}, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13223 loop is exited; and the function displays a message saying the number |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13224 of words in the region is one. In brief, the regular expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13225 search looks for and finds the word even though it is outside |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13226 the marked region. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13227 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13228 In the second manifestation of the bug, the region is whitespace at |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13229 the end of the buffer. Emacs says @samp{Search failed}. What happens |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13230 is that the true-or-false-test in the @code{while} loop tests true, so |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13231 the search expression is executed. But since there are no more words |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13232 in the buffer, the search fails. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13233 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13234 In both manifestations of the bug, the search extends or attempts to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13235 extend outside of the region. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13236 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13237 The solution is to limit the search to the region---this is a fairly |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13238 simple action, but as you may have come to expect, it is not quite as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13239 simple as you might think. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13240 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13241 As we have seen, the @code{re-search-forward} function takes a search |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13242 pattern as its first argument. But in addition to this first, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13243 mandatory argument, it accepts three optional arguments. The optional |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13244 second argument bounds the search. The optional third argument, if |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13245 @code{t}, causes the function to return @code{nil} rather than signal |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13246 an error if the search fails. The optional fourth argument is a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13247 repeat count. (In Emacs, you can see a function's documentation by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13248 typing @kbd{C-h f}, the name of the function, and then @key{RET}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13249 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13250 In the @code{count-words-region} definition, the value of the end of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13251 the region is held by the variable @code{end} which is passed as an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13252 argument to the function. Thus, we can add @code{end} as an argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13253 to the regular expression search expression: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13254 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13255 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13256 (re-search-forward "\\w+\\W*" end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13257 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13258 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13259 However, if you make only this change to the @code{count-words-region} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13260 definition and then test the new version of the definition on a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13261 stretch of whitespace, you will receive an error message saying |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13262 @samp{Search failed}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13263 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13264 What happens is this: the search is limited to the region, and fails |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13265 as you expect because there are no word-constituent characters in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13266 region. Since it fails, we receive an error message. But we do not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13267 want to receive an error message in this case; we want to receive the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13268 message that "The region does NOT have any words." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13269 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13270 The solution to this problem is to provide @code{re-search-forward} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13271 with a third argument of @code{t}, which causes the function to return |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13272 @code{nil} rather than signal an error if the search fails. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13273 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13274 However, if you make this change and try it, you will see the message |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13275 ``Counting words in region ... '' and @dots{} you will keep on seeing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13276 that message @dots{}, until you type @kbd{C-g} (@code{keyboard-quit}). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13277 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13278 Here is what happens: the search is limited to the region, as before, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13279 and it fails because there are no word-constituent characters in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13280 region, as expected. Consequently, the @code{re-search-forward} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13281 expression returns @code{nil}. It does nothing else. In particular, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13282 it does not move point, which it does as a side effect if it finds the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13283 search target. After the @code{re-search-forward} expression returns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13284 @code{nil}, the next expression in the @code{while} loop is evaluated. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13285 This expression increments the count. Then the loop repeats. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13286 true-or-false-test tests true because the value of point is still less |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13287 than the value of end, since the @code{re-search-forward} expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13288 did not move point. @dots{} and the cycle repeats @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13289 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13290 The @code{count-words-region} definition requires yet another |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13291 modification, to cause the true-or-false-test of the @code{while} loop |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13292 to test false if the search fails. Put another way, there are two |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13293 conditions that must be satisfied in the true-or-false-test before the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13294 word count variable is incremented: point must still be within the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13295 region and the search expression must have found a word to count. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13296 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13297 Since both the first condition and the second condition must be true |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13298 together, the two expressions, the region test and the search |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13299 expression, can be joined with an @code{and} special form and embedded in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13300 the @code{while} loop as the true-or-false-test, like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13301 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13302 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13303 (and (< (point) end) (re-search-forward "\\w+\\W*" end t)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13304 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13305 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13306 @c colon in printed section title causes problem in Info cross reference |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13307 @c also trouble with an overfull hbox |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13308 @iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13309 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13310 (For information about @code{and}, see |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13311 @ref{forward-paragraph, , @code{forward-paragraph}: a Goldmine of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13312 Functions}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13313 @end iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13314 @ifinfo |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13315 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13316 (@xref{forward-paragraph}, for information about @code{and}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13317 @end ifinfo |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13318 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13319 The @code{re-search-forward} expression returns @code{t} if the search |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13320 succeeds and as a side effect moves point. Consequently, as words are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13321 found, point is moved through the region. When the search |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13322 expression fails to find another word, or when point reaches the end |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13323 of the region, the true-or-false-test tests false, the @code{while} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13324 loop exists, and the @code{count-words-region} function displays one |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13325 or other of its messages. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13326 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13327 After incorporating these final changes, the @code{count-words-region} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13328 works without bugs (or at least, without bugs that I have found!). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13329 Here is what it looks like: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13330 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13331 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13332 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13333 ;;; @r{Final version:} @code{while} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13334 (defun count-words-region (beginning end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13335 "Print number of words in the region." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13336 (interactive "r") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13337 (message "Counting words in region ... ") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13338 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13339 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13340 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13341 ;;; @r{1. Set up appropriate conditions.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13342 (save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13343 (let ((count 0)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13344 (goto-char beginning) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13345 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13346 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13347 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13348 ;;; @r{2. Run the} while @r{loop.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13349 (while (and (< (point) end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13350 (re-search-forward "\\w+\\W*" end t)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13351 (setq count (1+ count))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13352 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13353 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13354 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13355 ;;; @r{3. Send a message to the user.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13356 (cond ((zerop count) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13357 (message |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13358 "The region does NOT have any words.")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13359 ((= 1 count) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13360 (message |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13361 "The region has 1 word.")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13362 (t |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13363 (message |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13364 "The region has %d words." count)))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13365 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13366 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13367 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13368 @node recursive-count-words, Counting Exercise, count-words-region, Counting Words |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13369 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13370 @section Count Words Recursively |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13371 @cindex Count words recursively |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13372 @cindex Recursively counting words |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13373 @cindex Words, counted recursively |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13374 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13375 You can write the function for counting words recursively as well as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13376 with a @code{while} loop. Let's see how this is done. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13377 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13378 First, we need to recognize that the @code{count-words-region} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13379 function has three jobs: it sets up the appropriate conditions for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13380 counting to occur; it counts the words in the region; and it sends a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13381 message to the user telling how many words there are. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13382 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13383 If we write a single recursive function to do everything, we will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13384 receive a message for every recursive call. If the region contains 13 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13385 words, we will receive thirteen messages, one right after the other. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13386 We don't want this! Instead, we must write two functions to do the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13387 job, one of which (the recursive function) will be used inside of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13388 other. One function will set up the conditions and display the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13389 message; the other will return the word count. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13390 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13391 Let us start with the function that causes the message to be displayed. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13392 We can continue to call this @code{count-words-region}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13393 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13394 This is the function that the user will call. It will be interactive. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13395 Indeed, it will be similar to our previous versions of this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13396 function, except that it will call @code{recursive-count-words} to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13397 determine how many words are in the region. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13398 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13399 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13400 We can readily construct a template for this function, based on our |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13401 previous versions: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13402 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13403 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13404 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13405 ;; @r{Recursive version; uses regular expression search} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13406 (defun count-words-region (beginning end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13407 "@var{documentation}@dots{}" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13408 (@var{interactive-expression}@dots{}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13409 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13410 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13411 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13412 ;;; @r{1. Set up appropriate conditions.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13413 (@var{explanatory message}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13414 (@var{set-up functions}@dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13415 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13416 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13417 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13418 ;;; @r{2. Count the words.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13419 @var{recursive call} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13420 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13421 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13422 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13423 ;;; @r{3. Send a message to the user.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13424 @var{message providing word count})) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13425 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13426 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13427 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13428 The definition looks straightforward, except that somehow the count |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13429 returned by the recursive call must be passed to the message |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13430 displaying the word count. A little thought suggests that this can be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13431 done by making use of a @code{let} expression: we can bind a variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13432 in the varlist of a @code{let} expression to the number of words in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13433 the region, as returned by the recursive call; and then the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13434 @code{cond} expression, using binding, can display the value to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13435 user. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13436 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13437 Often, one thinks of the binding within a @code{let} expression as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13438 somehow secondary to the `primary' work of a function. But in this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13439 case, what you might consider the `primary' job of the function, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13440 counting words, is done within the @code{let} expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13441 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13442 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13443 Using @code{let}, the function definition looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13444 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13445 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13446 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13447 (defun count-words-region (beginning end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13448 "Print number of words in the region." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13449 (interactive "r") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13450 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13451 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13452 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13453 ;;; @r{1. Set up appropriate conditions.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13454 (message "Counting words in region ... ") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13455 (save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13456 (goto-char beginning) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13457 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13458 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13459 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13460 ;;; @r{2. Count the words.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13461 (let ((count (recursive-count-words end))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13462 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13463 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13464 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13465 ;;; @r{3. Send a message to the user.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13466 (cond ((zerop count) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13467 (message |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13468 "The region does NOT have any words.")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13469 ((= 1 count) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13470 (message |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13471 "The region has 1 word.")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13472 (t |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13473 (message |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13474 "The region has %d words." count)))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13475 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13476 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13477 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13478 Next, we need to write the recursive counting function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13479 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13480 A recursive function has at least three parts: the `do-again-test', the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13481 `next-step-expression', and the recursive call. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13482 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13483 The do-again-test determines whether the function will or will not be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13484 called again. Since we are counting words in a region and can use a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13485 function that moves point forward for every word, the do-again-test |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13486 can check whether point is still within the region. The do-again-test |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13487 should find the value of point and determine whether point is before, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13488 at, or after the value of the end of the region. We can use the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13489 @code{point} function to locate point. Clearly, we must pass the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13490 value of the end of the region to the recursive counting function as an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13491 argument. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13492 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13493 In addition, the do-again-test should also test whether the search finds a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13494 word. If it does not, the function should not call itself again. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13495 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13496 The next-step-expression changes a value so that when the recursive |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13497 function is supposed to stop calling itself, it stops. More |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13498 precisely, the next-step-expression changes a value so that at the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13499 right time, the do-again-test stops the recursive function from |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13500 calling itself again. In this case, the next-step-expression can be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13501 the expression that moves point forward, word by word. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13502 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13503 The third part of a recursive function is the recursive call. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13504 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13505 Somewhere, also, we also need a part that does the `work' of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13506 function, a part that does the counting. A vital part! |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13507 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13508 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13509 But already, we have an outline of the recursive counting function: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13510 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13511 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13512 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13513 (defun recursive-count-words (region-end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13514 "@var{documentation}@dots{}" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13515 @var{do-again-test} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13516 @var{next-step-expression} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13517 @var{recursive call}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13518 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13519 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13520 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13521 Now we need to fill in the slots. Let's start with the simplest cases |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13522 first: if point is at or beyond the end of the region, there cannot |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13523 be any words in the region, so the function should return zero. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13524 Likewise, if the search fails, there are no words to count, so the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13525 function should return zero. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13526 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13527 On the other hand, if point is within the region and the search |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13528 succeeds, the function should call itself again. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13529 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13530 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13531 Thus, the do-again-test should look like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13532 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13533 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13534 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13535 (and (< (point) region-end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13536 (re-search-forward "\\w+\\W*" region-end t)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13537 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13538 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13539 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13540 Note that the search expression is part of the do-again-test---the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13541 function returns @code{t} if its search succeeds and @code{nil} if it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13542 fails. (@xref{Whitespace Bug, , The Whitespace Bug in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13543 @code{count-words-region}}, for an explanation of how |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13544 @code{re-search-forward} works.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13545 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13546 The do-again-test is the true-or-false test of an @code{if} clause. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13547 Clearly, if the do-again-test succeeds, the then-part of the @code{if} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13548 clause should call the function again; but if it fails, the else-part |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13549 should return zero since either point is outside the region or the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13550 search failed because there were no words to find. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13551 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13552 But before considering the recursive call, we need to consider the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13553 next-step-expression. What is it? Interestingly, it is the search |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13554 part of the do-again-test. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13555 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13556 In addition to returning @code{t} or @code{nil} for the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13557 do-again-test, @code{re-search-forward} moves point forward as a side |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13558 effect of a successful search. This is the action that changes the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13559 value of point so that the recursive function stops calling itself |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13560 when point completes its movement through the region. Consequently, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13561 the @code{re-search-forward} expression is the next-step-expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13562 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13563 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13564 In outline, then, the body of the @code{recursive-count-words} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13565 function looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13566 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13567 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13568 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13569 (if @var{do-again-test-and-next-step-combined} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13570 ;; @r{then} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13571 @var{recursive-call-returning-count} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13572 ;; @r{else} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13573 @var{return-zero}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13574 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13575 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13576 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13577 How to incorporate the mechanism that counts? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13578 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13579 If you are not used to writing recursive functions, a question like |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13580 this can be troublesome. But it can and should be approached |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13581 systematically. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13582 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13583 We know that the counting mechanism should be associated in some way |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13584 with the recursive call. Indeed, since the next-step-expression moves |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13585 point forward by one word, and since a recursive call is made for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13586 each word, the counting mechanism must be an expression that adds one |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13587 to the value returned by a call to @code{recursive-count-words}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13588 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13589 Consider several cases: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13590 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13591 @itemize @bullet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13592 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13593 If there are two words in the region, the function should return |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13594 a value resulting from adding one to the value returned when it counts |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13595 the first word, plus the number returned when it counts the remaining |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13596 words in the region, which in this case is one. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13597 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13598 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13599 If there is one word in the region, the function should return |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13600 a value resulting from adding one to the value returned when it counts |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13601 that word, plus the number returned when it counts the remaining |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13602 words in the region, which in this case is zero. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13603 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13604 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13605 If there are no words in the region, the function should return zero. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13606 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13607 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13608 From the sketch we can see that the else-part of the @code{if} returns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13609 zero for the case of no words. This means that the then-part of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13610 @code{if} must return a value resulting from adding one to the value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13611 returned from a count of the remaining words. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13612 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13613 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13614 The expression will look like this, where @code{1+} is a function that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13615 adds one to its argument. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13616 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13617 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13618 (1+ (recursive-count-words region-end)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13619 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13620 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13621 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13622 The whole @code{recursive-count-words} function will then look like |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13623 this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13624 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13625 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13626 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13627 (defun recursive-count-words (region-end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13628 "@var{documentation}@dots{}" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13629 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13630 ;;; @r{1. do-again-test} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13631 (if (and (< (point) region-end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13632 (re-search-forward "\\w+\\W*" region-end t)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13633 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13634 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13635 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13636 ;;; @r{2. then-part: the recursive call} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13637 (1+ (recursive-count-words region-end)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13638 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13639 ;;; @r{3. else-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13640 0)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13641 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13642 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13643 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13644 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13645 Let's examine how this works: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13646 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13647 If there are no words in the region, the else part of the @code{if} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13648 expression is evaluated and consequently the function returns zero. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13649 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13650 If there is one word in the region, the value of point is less than |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13651 the value of @code{region-end} and the search succeeds. In this case, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13652 the true-or-false-test of the @code{if} expression tests true, and the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13653 then-part of the @code{if} expression is evaluated. The counting |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13654 expression is evaluated. This expression returns a value (which will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13655 be the value returned by the whole function) that is the sum of one |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13656 added to the value returned by a recursive call. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13657 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13658 Meanwhile, the next-step-expression has caused point to jump over the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13659 first (and in this case only) word in the region. This means that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13660 when @code{(recursive-count-words region-end)} is evaluated a second |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13661 time, as a result of the recursive call, the value of point will be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13662 equal to or greater than the value of region end. So this time, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13663 @code{recursive-count-words} will return zero. The zero will be added |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13664 to one, and the original evaluation of @code{recursive-count-words} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13665 will return one plus zero, which is one, which is the correct amount. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13666 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13667 Clearly, if there are two words in the region, the first call to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13668 @code{recursive-count-words} returns one added to the value returned |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13669 by calling @code{recursive-count-words} on a region containing the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13670 remaining word---that is, it adds one to one, producing two, which is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13671 the correct amount. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13672 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13673 Similarly, if there are three words in the region, the first call to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13674 @code{recursive-count-words} returns one added to the value returned |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13675 by calling @code{recursive-count-words} on a region containing the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13676 remaining two words---and so on and so on. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13677 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13678 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13679 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13680 With full documentation the two functions look like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13681 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13682 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13683 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13684 The recursive function: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13685 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13686 @findex recursive-count-words |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13687 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13688 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13689 (defun recursive-count-words (region-end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13690 "Number of words between point and REGION-END." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13691 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13692 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13693 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13694 ;;; @r{1. do-again-test} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13695 (if (and (< (point) region-end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13696 (re-search-forward "\\w+\\W*" region-end t)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13697 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13698 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13699 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13700 ;;; @r{2. then-part: the recursive call} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13701 (1+ (recursive-count-words region-end)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13702 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13703 ;;; @r{3. else-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13704 0)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13705 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13706 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13707 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13708 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13709 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13710 The wrapper: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13711 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13712 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13713 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13714 ;;; @r{Recursive version} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13715 (defun count-words-region (beginning end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13716 "Print number of words in the region. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13717 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13718 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13719 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13720 Words are defined as at least one word-constituent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13721 character followed by at least one character that is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13722 not a word-constituent. The buffer's syntax table |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13723 determines which characters these are." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13724 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13725 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13726 (interactive "r") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13727 (message "Counting words in region ... ") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13728 (save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13729 (goto-char beginning) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13730 (let ((count (recursive-count-words end))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13731 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13732 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13733 (cond ((zerop count) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13734 (message |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13735 "The region does NOT have any words.")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13736 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13737 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13738 ((= 1 count) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13739 (message "The region has 1 word.")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13740 (t |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13741 (message |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13742 "The region has %d words." count)))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13743 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13744 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13745 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13746 @node Counting Exercise, , recursive-count-words, Counting Words |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13747 @section Exercise: Counting Punctuation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13748 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13749 Using a @code{while} loop, write a function to count the number of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13750 punctuation marks in a region---period, comma, semicolon, colon, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13751 exclamation mark, and question mark. Do the same using recursion. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13752 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13753 @node Words in a defun, Readying a Graph, Counting Words, Top |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13754 @chapter Counting Words in a @code{defun} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13755 @cindex Counting words in a @code{defun} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13756 @cindex Word counting in a @code{defun} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13757 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13758 Our next project is to count the number of words in a function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13759 definition. Clearly, this can be done using some variant of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13760 @code{count-word-region}. @xref{Counting Words, , Counting Words: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13761 Repetition and Regexps}. If we are just going to count the words in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13762 one definition, it is easy enough to mark the definition with the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13763 @kbd{C-M-h} (@code{mark-defun}) command, and then call |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13764 @code{count-word-region}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13765 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13766 However, I am more ambitious: I want to count the words and symbols in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13767 every definition in the Emacs sources and then print a graph that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13768 shows how many functions there are of each length: how many contain 40 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13769 to 49 words or symbols, how many contain 50 to 59 words or symbols, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13770 and so on. I have often been curious how long a typical function is, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13771 and this will tell. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13772 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13773 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13774 * Divide and Conquer:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13775 * Words and Symbols:: What to count? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13776 * Syntax:: What constitutes a word or symbol? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13777 * count-words-in-defun:: Very like @code{count-words}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13778 * Several defuns:: Counting several defuns in a file. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13779 * Find a File:: Do you want to look at a file? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13780 * lengths-list-file:: A list of the lengths of many definitions. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13781 * Several files:: Counting in definitions in different files. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13782 * Several files recursively:: Recursively counting in different files. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13783 * Prepare the data:: Prepare the data for display in a graph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13784 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13785 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13786 @node Divide and Conquer, Words and Symbols, Words in a defun, Words in a defun |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13787 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13788 @unnumberedsec Divide and Conquer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13789 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13790 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13791 Described in one phrase, the histogram project is daunting; but |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13792 divided into numerous small steps, each of which we can take one at a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13793 time, the project becomes less fearsome. Let us consider what the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13794 steps must be: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13795 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13796 @itemize @bullet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13797 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13798 First, write a function to count the words in one definition. This |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13799 includes the problem of handling symbols as well as words. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13801 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13802 Second, write a function to list the numbers of words in each function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13803 in a file. This function can use the @code{count-words-in-defun} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13804 function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13805 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13806 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13807 Third, write a function to list the numbers of words in each function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13808 in each of several files. This entails automatically finding the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13809 various files, switching to them, and counting the words in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13810 definitions within them. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13811 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13812 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13813 Fourth, write a function to convert the list of numbers that we |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13814 created in step three to a form that will be suitable for printing as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13815 a graph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13816 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13817 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13818 Fifth, write a function to print the results as a graph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13819 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13820 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13821 This is quite a project! But if we take each step slowly, it will not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13822 be difficult. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13823 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13824 @node Words and Symbols, Syntax, Divide and Conquer, Words in a defun |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13825 @section What to Count? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13826 @cindex Words and symbols in defun |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13827 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13828 When we first start thinking about how to count the words in a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13829 function definition, the first question is (or ought to be) what are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13830 we going to count? When we speak of `words' with respect to a Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13831 function definition, we are actually speaking, in large part, of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13832 `symbols'. For example, the following @code{multiply-by-seven} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13833 function contains the five symbols @code{defun}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13834 @code{multiply-by-seven}, @code{number}, @code{*}, and @code{7}. In |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13835 addition, in the documentation string, it contains the four words |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13836 @samp{Multiply}, @samp{NUMBER}, @samp{by}, and @samp{seven}. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13837 symbol @samp{number} is repeated, so the definition contains a total |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13838 of ten words and symbols. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13839 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13840 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13841 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13842 (defun multiply-by-seven (number) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13843 "Multiply NUMBER by seven." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13844 (* 7 number)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13845 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13846 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13847 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13848 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13849 However, if we mark the @code{multiply-by-seven} definition with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13850 @kbd{C-M-h} (@code{mark-defun}), and then call |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13851 @code{count-words-region} on it, we will find that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13852 @code{count-words-region} claims the definition has eleven words, not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13853 ten! Something is wrong! |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13854 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13855 The problem is twofold: @code{count-words-region} does not count the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13856 @samp{*} as a word, and it counts the single symbol, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13857 @code{multiply-by-seven}, as containing three words. The hyphens are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13858 treated as if they were interword spaces rather than intraword |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13859 connectors: @samp{multiply-by-seven} is counted as if it were written |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13860 @samp{multiply by seven}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13861 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13862 The cause of this confusion is the regular expression search within |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13863 the @code{count-words-region} definition that moves point forward word |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13864 by word. In the canonical version of @code{count-words-region}, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13865 regexp is: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13866 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13867 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13868 "\\w+\\W*" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13869 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13870 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13871 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13872 This regular expression is a pattern defining one or more word |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13873 constituent characters possibly followed by one or more characters |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13874 that are not word constituents. What is meant by `word constituent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13875 characters' brings us to the issue of syntax, which is worth a section |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13876 of its own. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13877 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13878 @node Syntax, count-words-in-defun, Words and Symbols, Words in a defun |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13879 @section What Constitutes a Word or Symbol? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13880 @cindex Syntax categories and tables |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13881 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13882 Emacs treats different characters as belonging to different |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13883 @dfn{syntax categories}. For example, the regular expression, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13884 @samp{\\w+}, is a pattern specifying one or more @emph{word |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13885 constituent} characters. Word constituent characters are members of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13886 one syntax category. Other syntax categories include the class of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13887 punctuation characters, such as the period and the comma, and the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13888 class of whitespace characters, such as the blank space and the tab |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13889 character. (For more information, see @ref{Syntax, Syntax, The Syntax |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13890 Table, emacs, The GNU Emacs Manual}, and @ref{Syntax Tables, , Syntax |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13891 Tables, elisp, The GNU Emacs Lisp Reference Manual}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13892 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13893 Syntax tables specify which characters belong to which categories. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13894 Usually, a hyphen is not specified as a `word constituent character'. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13895 Instead, it is specified as being in the `class of characters that are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13896 part of symbol names but not words.' This means that the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13897 @code{count-words-region} function treats it in the same way it treats |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13898 an interword white space, which is why @code{count-words-region} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13899 counts @samp{multiply-by-seven} as three words. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13900 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13901 There are two ways to cause Emacs to count @samp{multiply-by-seven} as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13902 one symbol: modify the syntax table or modify the regular expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13903 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13904 We could redefine a hyphen as a word constituent character by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13905 modifying the syntax table that Emacs keeps for each mode. This |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13906 action would serve our purpose, except that a hyphen is merely the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13907 most common character within symbols that is not typically a word |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13908 constituent character; there are others, too. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13909 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13910 Alternatively, we can redefine the regular expression used in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13911 @code{count-words} definition so as to include symbols. This |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13912 procedure has the merit of clarity, but the task is a little tricky. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13913 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13914 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13915 The first part is simple enough: the pattern must match ``at least one |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13916 character that is a word or symbol constituent''. Thus: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13917 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13918 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13919 "\\(\\w\\|\\s_\\)+" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13920 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13921 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13922 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13923 The @samp{\\(} is the first part of the grouping construct that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13924 includes the @samp{\\w} and the @samp{\\s_} as alternatives, separated |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13925 by the @samp{\\|}. The @samp{\\w} matches any word-constituent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13926 character and the @samp{\\s_} matches any character that is part of a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13927 symbol name but not a word-constituent character. The @samp{+} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13928 following the group indicates that the word or symbol constituent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13929 characters must be matched at least once. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13930 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13931 However, the second part of the regexp is more difficult to design. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13932 What we want is to follow the first part with ``optionally one or more |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13933 characters that are not constituents of a word or symbol''. At first, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13934 I thought I could define this with the following: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13935 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13936 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13937 "\\(\\W\\|\\S_\\)*" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13938 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13939 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13940 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13941 The upper case @samp{W} and @samp{S} match characters that are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13942 @emph{not} word or symbol constituents. Unfortunately, this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13943 expression matches any character that is either not a word constituent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13944 or not a symbol constituent. This matches any character! |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13945 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13946 I then noticed that every word or symbol in my test region was |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13947 followed by white space (blank space, tab, or newline). So I tried |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13948 placing a pattern to match one or more blank spaces after the pattern |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13949 for one or more word or symbol constituents. This failed, too. Words |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13950 and symbols are often separated by whitespace, but in actual code |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13951 parentheses may follow symbols and punctuation may follow words. So |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13952 finally, I designed a pattern in which the word or symbol constituents |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13953 are followed optionally by characters that are not white space and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13954 then followed optionally by white space. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13955 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13956 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13957 Here is the full regular expression: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13958 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13959 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13960 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13961 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13962 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13963 @node count-words-in-defun, Several defuns, Syntax, Words in a defun |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13964 @section The @code{count-words-in-defun} Function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13965 @cindex Counting words in a @code{defun} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13966 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13967 We have seen that there are several ways to write a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13968 @code{count-word-region} function. To write a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13969 @code{count-words-in-defun}, we need merely adapt one of these |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13970 versions. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13971 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13972 The version that uses a @code{while} loop is easy to understand, so I |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13973 am going to adapt that. Because @code{count-words-in-defun} will be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13974 part of a more complex program, it need not be interactive and it need |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13975 not display a message but just return the count. These considerations |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13976 simplify the definition a little. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13977 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13978 On the other hand, @code{count-words-in-defun} will be used within a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13979 buffer that contains function definitions. Consequently, it is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13980 reasonable to ask that the function determine whether it is called |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13981 when point is within a function definition, and if it is, to return |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13982 the count for that definition. This adds complexity to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13983 definition, but saves us from needing to pass arguments to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13984 function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13985 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13986 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13987 These considerations lead us to prepare the following template: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13988 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13989 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13990 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13991 (defun count-words-in-defun () |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13992 "@var{documentation}@dots{}" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13993 (@var{set up}@dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13994 (@var{while loop}@dots{}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13995 @var{return count}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13996 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13997 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13998 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
13999 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14000 As usual, our job is to fill in the slots. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14001 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14002 First, the set up. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14003 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14004 We are presuming that this function will be called within a buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14005 containing function definitions. Point will either be within a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14006 function definition or not. For @code{count-words-in-defun} to work, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14007 point must move to the beginning of the definition, a counter must |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14008 start at zero, and the counting loop must stop when point reaches the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14009 end of the definition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14010 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14011 The @code{beginning-of-defun} function searches backwards for an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14012 opening delimiter such as a @samp{(} at the beginning of a line, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14013 moves point to that position, or else to the limit of the search. In |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14014 practice, this means that @code{beginning-of-defun} moves point to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14015 beginning of an enclosing or preceding function definition, or else to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14016 the beginning of the buffer. We can use @code{beginning-of-defun} to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14017 place point where we wish to start. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14018 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14019 The @code{while} loop requires a counter to keep track of the words or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14020 symbols being counted. A @code{let} expression can be used to create |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14021 a local variable for this purpose, and bind it to an initial value of zero. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14022 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14023 The @code{end-of-defun} function works like @code{beginning-of-defun} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14024 except that it moves point to the end of the definition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14025 @code{end-of-defun} can be used as part of an expression that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14026 determines the position of the end of the definition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14027 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14028 The set up for @code{count-words-in-defun} takes shape rapidly: first |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14029 we move point to the beginning of the definition, then we create a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14030 local variable to hold the count, and finally, we record the position |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14031 of the end of the definition so the @code{while} loop will know when to stop |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14032 looping. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14033 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14034 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14035 The code looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14036 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14037 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14038 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14039 (beginning-of-defun) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14040 (let ((count 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14041 (end (save-excursion (end-of-defun) (point)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14042 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14043 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14044 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14045 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14046 The code is simple. The only slight complication is likely to concern |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14047 @code{end}: it is bound to the position of the end of the definition |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14048 by a @code{save-excursion} expression that returns the value of point |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14049 after @code{end-of-defun} temporarily moves it to the end of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14050 definition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14051 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14052 The second part of the @code{count-words-in-defun}, after the set up, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14053 is the @code{while} loop. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14054 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14055 The loop must contain an expression that jumps point forward word by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14056 word and symbol by symbol, and another expression that counts the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14057 jumps. The true-or-false-test for the @code{while} loop should test |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14058 true so long as point should jump forward, and false when point is at |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14059 the end of the definition. We have already redefined the regular |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14060 expression for this (@pxref{Syntax}), so the loop is straightforward: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14061 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14062 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14063 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14064 (while (and (< (point) end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14065 (re-search-forward |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14066 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" end t) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14067 (setq count (1+ count))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14068 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14069 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14070 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14071 The third part of the function definition returns the count of words |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14072 and symbols. This part is the last expression within the body of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14073 @code{let} expression, and can be, very simply, the local variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14074 @code{count}, which when evaluated returns the count. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14075 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14076 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14077 Put together, the @code{count-words-in-defun} definition looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14078 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14079 @findex count-words-in-defun |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14080 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14081 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14082 (defun count-words-in-defun () |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14083 "Return the number of words and symbols in a defun." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14084 (beginning-of-defun) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14085 (let ((count 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14086 (end (save-excursion (end-of-defun) (point)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14087 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14088 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14089 (while |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14090 (and (< (point) end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14091 (re-search-forward |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14092 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14093 end t)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14094 (setq count (1+ count))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14095 count)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14096 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14097 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14098 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14099 How to test this? The function is not interactive, but it is easy to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14100 put a wrapper around the function to make it interactive; we can use |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14101 almost the same code as for the recursive version of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14102 @code{count-words-region}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14103 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14104 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14105 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14106 ;;; @r{Interactive version.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14107 (defun count-words-defun () |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14108 "Number of words and symbols in a function definition." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14109 (interactive) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14110 (message |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14111 "Counting words and symbols in function definition ... ") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14112 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14113 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14114 (let ((count (count-words-in-defun))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14115 (cond |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14116 ((zerop count) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14117 (message |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14118 "The definition does NOT have any words or symbols.")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14119 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14120 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14121 ((= 1 count) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14122 (message |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14123 "The definition has 1 word or symbol.")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14124 (t |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14125 (message |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14126 "The definition has %d words or symbols." count))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14127 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14128 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14129 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14130 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14131 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14132 Let's re-use @kbd{C-c =} as a convenient keybinding: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14133 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14134 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14135 (global-set-key "\C-c=" 'count-words-defun) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14136 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14137 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14138 Now we can try out @code{count-words-defun}: install both |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14139 @code{count-words-in-defun} and @code{count-words-defun}, and set the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14140 keybinding, and then place the cursor within the following definition: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14141 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14142 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14143 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14144 (defun multiply-by-seven (number) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14145 "Multiply NUMBER by seven." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14146 (* 7 number)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14147 @result{} 10 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14148 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14149 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14150 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14151 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14152 Success! The definition has 10 words and symbols. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14153 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14154 The next problem is to count the numbers of words and symbols in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14155 several definitions within a single file. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14156 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14157 @node Several defuns, Find a File, count-words-in-defun, Words in a defun |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14158 @section Count Several @code{defuns} Within a File |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14159 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14160 A file such as @file{simple.el} may have 80 or more function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14161 definitions within it. Our long term goal is to collect statistics on |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14162 many files, but as a first step, our immediate goal is to collect |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14163 statistics on one file. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14164 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14165 The information will be a series of numbers, each number being the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14166 length of a function definition. We can store the numbers in a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14167 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14168 We know that we will want to incorporate the information regarding one |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14169 file with information about many other files; this means that the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14170 function for counting definition lengths within one file need only |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14171 return the list of lengths. It need not and should not display any |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14172 messages. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14173 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14174 The word count commands contain one expression to jump point forward |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14175 word by word and another expression to count the jumps. The function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14176 to return the lengths of definitions can be designed to work the same |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14177 way, with one expression to jump point forward definition by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14178 definition and another expression to construct the lengths' list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14179 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14180 This statement of the problem makes it elementary to write the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14181 function definition. Clearly, we will start the count at the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14182 beginning of the file, so the first command will be @code{(goto-char |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14183 (point-min))}. Next, we start the @code{while} loop; and the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14184 true-or-false test of the loop can be a regular expression search for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14185 the next function definition---so long as the search succeeds, point |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14186 is moved forward and then the body of the loop is evaluated. The body |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14187 needs an expression that constructs the lengths' list. @code{cons}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14188 the list construction command, can be used to create the list. That |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14189 is almost all there is to it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14190 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14191 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14192 Here is what this fragment of code looks like: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14193 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14194 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14195 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14196 (goto-char (point-min)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14197 (while (re-search-forward "^(defun" nil t) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14198 (setq lengths-list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14199 (cons (count-words-in-defun) lengths-list))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14200 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14201 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14202 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14203 What we have left out is the mechanism for finding the file that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14204 contains the function definitions. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14205 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14206 In previous examples, we either used this, the Info file, or we |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14207 switched back and forth to some other buffer, such as the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14208 @file{*scratch*} buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14209 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14210 Finding a file is a new process that we have not yet discussed. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14211 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14212 @node Find a File, lengths-list-file, Several defuns, Words in a defun |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14213 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14214 @section Find a File |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14215 @cindex Find a File |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14216 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14217 To find a file in Emacs, you use the @kbd{C-x C-f} (@code{find-file}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14218 command. This command is almost, but not quite right for the lengths |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14219 problem. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14220 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14221 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14222 Let's look at the source for @code{find-file} (you can use the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14223 @code{find-tag} command or @kbd{C-h f} (@code{describe-function}) to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14224 find the source of a function): |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14225 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14226 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14227 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14228 (defun find-file (filename) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14229 "Edit file FILENAME. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14230 Switch to a buffer visiting file FILENAME, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14231 creating one if none already exists." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14232 (interactive "FFind file: ") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14233 (switch-to-buffer (find-file-noselect filename))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14234 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14235 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14236 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14237 The definition possesses short but complete documentation and an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14238 interactive specification that prompts you for a file name when you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14239 use the command interactively. The body of the definition contains |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14240 two functions, @code{find-file-noselect} and @code{switch-to-buffer}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14241 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14242 According to its documentation as shown by @kbd{C-h f} (the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14243 @code{describe-function} command), the @code{find-file-noselect} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14244 function reads the named file into a buffer and returns the buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14245 However, the buffer is not selected. Emacs does not switch its |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14246 attention (or yours if you are using @code{find-file-noselect}) to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14247 named buffer. That is what @code{switch-to-buffer} does: it switches |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14248 the buffer to which Emacs attention is directed; and it switches the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14249 buffer displayed in the window to the new buffer. We have discussed |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14250 buffer switching elsewhere. (@xref{Switching Buffers}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14251 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14252 In this histogram project, we do not need to display each file on the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14253 screen as the program determines the length of each definition within |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14254 it. Instead of employing @code{switch-to-buffer}, we can work with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14255 @code{set-buffer}, which redirects the attention of the computer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14256 program to a different buffer but does not redisplay it on the screen. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14257 So instead of calling on @code{find-file} to do the job, we must write |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14258 our own expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14259 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14260 The task is easy: use @code{find-file-noselect} and @code{set-buffer}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14261 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14262 @node lengths-list-file, Several files, Find a File, Words in a defun |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14263 @section @code{lengths-list-file} in Detail |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14264 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14265 The core of the @code{lengths-list-file} function is a @code{while} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14266 loop containing a function to move point forward `defun by defun' and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14267 a function to count the number of words and symbols in each defun. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14268 This core must be surrounded by functions that do various other tasks, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14269 including finding the file, and ensuring that point starts out at the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14270 beginning of the file. The function definition looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14271 @findex lengths-list-file |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14272 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14273 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14274 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14275 (defun lengths-list-file (filename) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14276 "Return list of definitions' lengths within FILE. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14277 The returned list is a list of numbers. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14278 Each number is the number of words or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14279 symbols in one function definition." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14280 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14281 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14282 (message "Working on `%s' ... " filename) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14283 (save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14284 (let ((buffer (find-file-noselect filename)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14285 (lengths-list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14286 (set-buffer buffer) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14287 (setq buffer-read-only t) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14288 (widen) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14289 (goto-char (point-min)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14290 (while (re-search-forward "^(defun" nil t) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14291 (setq lengths-list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14292 (cons (count-words-in-defun) lengths-list))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14293 (kill-buffer buffer) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14294 lengths-list))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14295 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14296 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14297 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14298 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14299 The function is passed one argument, the name of the file on which it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14300 will work. It has four lines of documentation, but no interactive |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14301 specification. Since people worry that a computer is broken if they |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14302 don't see anything going on, the first line of the body is a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14303 message. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14304 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14305 The next line contains a @code{save-excursion} that returns Emacs' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14306 attention to the current buffer when the function completes. This is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14307 useful in case you embed this function in another function that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14308 presumes point is restored to the original buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14309 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14310 In the varlist of the @code{let} expression, Emacs finds the file and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14311 binds the local variable @code{buffer} to the buffer containing the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14312 file. At the same time, Emacs creates @code{lengths-list} as a local |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14313 variable. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14314 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14315 Next, Emacs switches its attention to the buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14316 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14317 In the following line, Emacs makes the buffer read-only. Ideally, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14318 this line is not necessary. None of the functions for counting words |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14319 and symbols in a function definition should change the buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14320 Besides, the buffer is not going to be saved, even if it were changed. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14321 This line is entirely the consequence of great, perhaps excessive, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14322 caution. The reason for the caution is that this function and those |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14323 it calls work on the sources for Emacs and it is very inconvenient if |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14324 they are inadvertently modified. It goes without saying that I did |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14325 not realize a need for this line until an experiment went awry and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14326 started to modify my Emacs source files @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14327 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14328 Next comes a call to widen the buffer if it is narrowed. This |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14329 function is usually not needed---Emacs creates a fresh buffer if none |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14330 already exists; but if a buffer visiting the file already exists Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14331 returns that one. In this case, the buffer may be narrowed and must |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14332 be widened. If we wanted to be fully `user-friendly', we would |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14333 arrange to save the restriction and the location of point, but we |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14334 won't. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14335 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14336 The @code{(goto-char (point-min))} expression moves point to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14337 beginning of the buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14338 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14339 Then comes a @code{while} loop in which the `work' of the function is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14340 carried out. In the loop, Emacs determines the length of each |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14341 definition and constructs a lengths' list containing the information. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14342 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14343 Emacs kills the buffer after working through it. This is to save |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14344 space inside of Emacs. My version of Emacs 19 contained over 300 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14345 source files of interest; Emacs 21 contains over 800 source files. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14346 Another function will apply @code{lengths-list-file} to each of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14347 files. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14348 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14349 Finally, the last expression within the @code{let} expression is the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14350 @code{lengths-list} variable; its value is returned as the value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14351 the whole function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14352 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14353 You can try this function by installing it in the usual fashion. Then |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14354 place your cursor after the following expression and type @kbd{C-x |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14355 C-e} (@code{eval-last-sexp}). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14356 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14357 @c !!! 21.0.100 lisp sources location here |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14358 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14359 (lengths-list-file |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14360 "/usr/local/share/emacs/21.0.100/lisp/emacs-lisp/debug.el") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14361 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14362 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14363 @c was: (lengths-list-file "../lisp/debug.el") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14364 @c !!! as of 21, Info file is in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14365 @c /usr/share/info/emacs-lisp-intro.info.gz |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14366 @c but debug.el is in /usr/local/share/emacs/21.0.100/lisp/emacs-lisp/debug.el |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14367 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14368 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14369 (You may need to change the pathname of the file; the one here worked |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14370 with GNU Emacs version 21.0.100. To change the expression, copy it to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14371 the @file{*scratch*} buffer and edit it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14372 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14373 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14374 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14375 (Also, to see the full length of the list, rather than a truncated |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14376 version, you may have to evaluate the following: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14377 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14378 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14379 (custom-set-variables '(eval-expression-print-length nil)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14380 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14381 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14382 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14383 (@xref{defcustom, , Setting Variables with @code{defcustom}}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14384 Then evaluate the @code{lengths-list-file} expression.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14385 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14386 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14387 The lengths' list for @file{debug.el} takes less than a second to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14388 produce and looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14389 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14390 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14391 (77 95 85 87 131 89 50 25 44 44 68 35 64 45 17 34 167 457) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14392 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14393 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14394 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14395 (Using my old machine, the version 19 lengths' list for @file{debug.el} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14396 took seven seconds to produce and looked like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14397 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14398 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14399 (75 41 80 62 20 45 44 68 45 12 34 235) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14400 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14401 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14402 (The newer version of @file{debug.el} contains more defuns than the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14403 earlier one; and my new machine is much faster than the old one.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14404 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14405 Note that the length of the last definition in the file is first in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14406 the list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14407 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14408 @node Several files, Several files recursively, lengths-list-file, Words in a defun |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14409 @section Count Words in @code{defuns} in Different Files |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14410 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14411 In the previous section, we created a function that returns a list of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14412 the lengths of each definition in a file. Now, we want to define a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14413 function to return a master list of the lengths of the definitions in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14414 a list of files. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14415 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14416 Working on each of a list of files is a repetitious act, so we can use |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14417 either a @code{while} loop or recursion. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14418 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14419 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14420 * lengths-list-many-files:: Return a list of the lengths of defuns. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14421 * append:: Attach one list to another. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14422 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14423 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14424 @node lengths-list-many-files, append, Several files, Several files |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14425 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14426 @unnumberedsubsec Determine the lengths of @code{defuns} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14427 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14428 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14429 The design using a @code{while} loop is routine. The argument passed |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14430 the function is a list of files. As we saw earlier (@pxref{Loop |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14431 Example}), you can write a @code{while} loop so that the body of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14432 loop is evaluated if such a list contains elements, but to exit the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14433 loop if the list is empty. For this design to work, the body of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14434 loop must contain an expression that shortens the list each time the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14435 body is evaluated, so that eventually the list is empty. The usual |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14436 technique is to set the value of the list to the value of the @sc{cdr} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14437 of the list each time the body is evaluated. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14438 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14439 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14440 The template looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14441 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14442 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14443 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14444 (while @var{test-whether-list-is-empty} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14445 @var{body}@dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14446 @var{set-list-to-cdr-of-list}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14447 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14448 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14449 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14450 Also, we remember that a @code{while} loop returns @code{nil} (the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14451 result of evaluating the true-or-false-test), not the result of any |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14452 evaluation within its body. (The evaluations within the body of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14453 loop are done for their side effects.) However, the expression that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14454 sets the lengths' list is part of the body---and that is the value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14455 that we want returned by the function as a whole. To do this, we |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14456 enclose the @code{while} loop within a @code{let} expression, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14457 arrange that the last element of the @code{let} expression contains |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14458 the value of the lengths' list. (@xref{Incrementing Example, , Loop |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14459 Example with an Incrementing Counter}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14460 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14461 @findex lengths-list-many-files |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14462 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14463 These considerations lead us directly to the function itself: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14464 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14465 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14466 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14467 ;;; @r{Use @code{while} loop.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14468 (defun lengths-list-many-files (list-of-files) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14469 "Return list of lengths of defuns in LIST-OF-FILES." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14470 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14471 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14472 (let (lengths-list) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14473 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14474 ;;; @r{true-or-false-test} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14475 (while list-of-files |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14476 (setq lengths-list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14477 (append |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14478 lengths-list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14479 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14480 ;;; @r{Generate a lengths' list.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14481 (lengths-list-file |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14482 (expand-file-name (car list-of-files))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14483 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14484 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14485 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14486 ;;; @r{Make files' list shorter.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14487 (setq list-of-files (cdr list-of-files))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14488 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14489 ;;; @r{Return final value of lengths' list.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14490 lengths-list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14491 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14492 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14493 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14494 @code{expand-file-name} is a built-in function that converts a file |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14495 name to the absolute, long, path name form of the directory in which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14496 the function is called. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14497 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14498 @c !!! 21.0.100 lisp sources location here |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14499 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14500 Thus, if @code{expand-file-name} is called on @code{debug.el} when |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14501 Emacs is visiting the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14502 @file{/usr/local/share/emacs/21.0.100/lisp/emacs-lisp/} directory, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14503 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14504 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14505 debug.el |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14506 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14507 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14508 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14509 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14510 becomes |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14511 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14512 @c !!! 21.0.100 lisp sources location here |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14513 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14514 /usr/local/share/emacs/21.0.100/lisp/emacs-lisp/debug.el |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14515 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14516 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14517 The only other new element of this function definition is the as yet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14518 unstudied function @code{append}, which merits a short section for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14519 itself. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14520 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14521 @node append, , lengths-list-many-files, Several files |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14522 @subsection The @code{append} Function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14523 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14524 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14525 The @code{append} function attaches one list to another. Thus, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14526 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14527 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14528 (append '(1 2 3 4) '(5 6 7 8)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14529 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14530 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14531 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14532 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14533 produces the list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14534 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14535 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14536 (1 2 3 4 5 6 7 8) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14537 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14538 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14539 This is exactly how we want to attach two lengths' lists produced by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14540 @code{lengths-list-file} to each other. The results contrast with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14541 @code{cons}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14542 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14543 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14544 (cons '(1 2 3 4) '(5 6 7 8)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14545 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14546 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14547 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14548 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14549 which constructs a new list in which the first argument to @code{cons} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14550 becomes the first element of the new list: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14551 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14552 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14553 ((1 2 3 4) 5 6 7 8) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14554 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14555 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14556 @node Several files recursively, Prepare the data, Several files, Words in a defun |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14557 @section Recursively Count Words in Different Files |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14558 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14559 Besides a @code{while} loop, you can work on each of a list of files |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14560 with recursion. A recursive version of @code{lengths-list-many-files} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14561 is short and simple. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14562 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14563 The recursive function has the usual parts: the `do-again-test', the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14564 `next-step-expression', and the recursive call. The `do-again-test' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14565 determines whether the function should call itself again, which it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14566 will do if the @code{list-of-files} contains any remaining elements; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14567 the `next-step-expression' resets the @code{list-of-files} to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14568 @sc{cdr} of itself, so eventually the list will be empty; and the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14569 recursive call calls itself on the shorter list. The complete |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14570 function is shorter than this description! |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14571 @findex recursive-lengths-list-many-files |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14572 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14573 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14574 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14575 (defun recursive-lengths-list-many-files (list-of-files) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14576 "Return list of lengths of each defun in LIST-OF-FILES." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14577 (if list-of-files ; @r{do-again-test} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14578 (append |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14579 (lengths-list-file |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14580 (expand-file-name (car list-of-files))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14581 (recursive-lengths-list-many-files |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14582 (cdr list-of-files))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14583 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14584 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14585 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14586 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14587 In a sentence, the function returns the lengths' list for the first of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14588 the @code{list-of-files} appended to the result of calling itself on |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14589 the rest of the @code{list-of-files}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14590 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14591 Here is a test of @code{recursive-lengths-list-many-files}, along with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14592 the results of running @code{lengths-list-file} on each of the files |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14593 individually. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14594 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14595 Install @code{recursive-lengths-list-many-files} and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14596 @code{lengths-list-file}, if necessary, and then evaluate the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14597 following expressions. You may need to change the files' pathnames; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14598 those here work when this Info file and the Emacs sources are located |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14599 in their customary places. To change the expressions, copy them to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14600 the @file{*scratch*} buffer, edit them, and then evaluate them. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14601 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14602 The results are shown after the @samp{@result{}}. (These results are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14603 for files from Emacs Version 21.0.100; files from other versions of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14604 Emacs may produce different results.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14605 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14606 @c !!! 21.0.100 lisp sources location here |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14607 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14608 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14609 (cd "/usr/local/share/emacs/21.0.100/") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14610 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14611 (lengths-list-file "./lisp/macros.el") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14612 @result{} (273 263 456 90) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14613 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14614 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14615 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14616 (lengths-list-file "./lisp/mail/mailalias.el") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14617 @result{} (38 32 26 77 174 180 321 198 324) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14618 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14619 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14620 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14621 (lengths-list-file "./lisp/makesum.el") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14622 @result{} (85 181) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14623 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14624 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14625 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14626 (recursive-lengths-list-many-files |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14627 '("./lisp/macros.el" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14628 "./lisp/mail/mailalias.el" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14629 "./lisp/makesum.el")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14630 @result{} (273 263 456 90 38 32 26 77 174 180 321 198 324 85 181) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14631 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14632 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14633 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14634 The @code{recursive-lengths-list-many-files} function produces the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14635 output we want. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14636 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14637 The next step is to prepare the data in the list for display in a graph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14638 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14639 @node Prepare the data, , Several files recursively, Words in a defun |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14640 @section Prepare the Data for Display in a Graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14641 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14642 The @code{recursive-lengths-list-many-files} function returns a list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14643 of numbers. Each number records the length of a function definition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14644 What we need to do now is transform this data into a list of numbers |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14645 suitable for generating a graph. The new list will tell how many |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14646 functions definitions contain less than 10 words and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14647 symbols, how many contain between 10 and 19 words and symbols, how |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14648 many contain between 20 and 29 words and symbols, and so on. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14649 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14650 In brief, we need to go through the lengths' list produced by the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14651 @code{recursive-lengths-list-many-files} function and count the number |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14652 of defuns within each range of lengths, and produce a list of those |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14653 numbers. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14654 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14655 Based on what we have done before, we can readily foresee that it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14656 should not be too hard to write a function that `@sc{cdr}s' down the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14657 lengths' list, looks at each element, determines which length range it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14658 is in, and increments a counter for that range. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14659 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14660 However, before beginning to write such a function, we should consider |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14661 the advantages of sorting the lengths' list first, so the numbers are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14662 ordered from smallest to largest. First, sorting will make it easier |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14663 to count the numbers in each range, since two adjacent numbers will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14664 either be in the same length range or in adjacent ranges. Second, by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14665 inspecting a sorted list, we can discover the highest and lowest |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14666 number, and thereby determine the largest and smallest length range |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14667 that we will need. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14668 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14669 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14670 * Sorting:: Sorting lists. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14671 * Files List:: Making a list of files. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14672 * Counting function definitions:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14673 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14674 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14675 @node Sorting, Files List, Prepare the data, Prepare the data |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14676 @subsection Sorting Lists |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14677 @findex sort |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14678 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14679 Emacs contains a function to sort lists, called (as you might guess) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14680 @code{sort}. The @code{sort} function takes two arguments, the list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14681 to be sorted, and a predicate that determines whether the first of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14682 two list elements is ``less'' than the second. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14683 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14684 As we saw earlier (@pxref{Wrong Type of Argument, , Using the Wrong |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14685 Type Object as an Argument}), a predicate is a function that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14686 determines whether some property is true or false. The @code{sort} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14687 function will reorder a list according to whatever property the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14688 predicate uses; this means that @code{sort} can be used to sort |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14689 non-numeric lists by non-numeric criteria---it can, for example, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14690 alphabetize a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14691 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14692 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14693 The @code{<} function is used when sorting a numeric list. For example, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14694 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14695 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14696 (sort '(4 8 21 17 33 7 21 7) '<) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14697 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14698 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14699 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14700 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14701 produces this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14702 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14703 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14704 (4 7 7 8 17 21 21 33) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14705 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14706 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14707 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14708 (Note that in this example, both the arguments are quoted so that the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14709 symbols are not evaluated before being passed to @code{sort} as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14710 arguments.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14711 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14712 Sorting the list returned by the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14713 @code{recursive-lengths-list-many-files} function is straightforward; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14714 it uses the @code{<} function: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14715 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14716 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14717 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14718 (sort |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14719 (recursive-lengths-list-many-files |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14720 '("../lisp/macros.el" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14721 "../lisp/mailalias.el" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14722 "../lisp/makesum.el")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14723 '< |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14724 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14725 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14726 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14727 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14728 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14729 which produces: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14730 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14731 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14732 (85 86 116 122 154 176 179 265) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14733 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14734 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14735 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14736 (Note that in this example, the first argument to @code{sort} is not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14737 quoted, since the expression must be evaluated so as to produce the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14738 list that is passed to @code{sort}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14739 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14740 @node Files List, Counting function definitions, Sorting, Prepare the data |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14741 @subsection Making a List of Files |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14742 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14743 The @code{recursive-lengths-list-many-files} function requires a list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14744 of files as its argument. For our test examples, we constructed such |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14745 a list by hand; but the Emacs Lisp source directory is too large for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14746 us to do for that. Instead, we will write a function to do the job |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14747 for us. In this function, we will use both a @code{while} loop and a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14748 recursive call. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14749 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14750 @findex directory-files |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14751 We did not have to write a function like this for older versions of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14752 GNU Emacs, since they placed all the @samp{.el} files in one |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14753 directory. Instead, we were able to use the @code{directory-files} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14754 function, which lists the names of files that match a specified |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14755 pattern within a single directory. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14756 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14757 However, recent versions of Emacs place Emacs Lisp files in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14758 sub-directories of the top level @file{lisp} directory. This |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14759 re-arrangement eases navigation. For example, all the mail related |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14760 files are in a @file{lisp} sub-directory called @file{mail}. But at |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14761 the same time, this arrangement forces us to create a file listing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14762 function that descends into the sub-directories. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14763 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14764 @findex files-in-below-directory |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14765 We can create this function, called @code{files-in-below-directory}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14766 using familiar functions such as @code{car}, @code{nthcdr}, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14767 @code{substring} in conjunction with an existing function called |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14768 @code{directory-files-and-attributes}. This latter function not only |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14769 lists all the filenames in a directory, including the names |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14770 of sub-directories, but also their attributes. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14771 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14772 To restate our goal: to create a function that will enable us |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14773 to feed filenames to @code{recursive-lengths-list-many-files} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14774 as a list that looks like this (but with more elements): |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14775 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14776 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14777 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14778 ("../lisp/macros.el" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14779 "../lisp/mail/rmail.el" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14780 "../lisp/makesum.el") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14781 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14782 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14783 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14784 The @code{directory-files-and-attributes} function returns a list of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14785 lists. Each of the lists within the main list consists of 13 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14786 elements. The first element is a string that contains the name of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14787 file -- which, in GNU/Linux, may be a `directory file', that is to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14788 say, a file with the special attributes of a directory. The second |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14789 element of the list is @code{t} for a directory, a string |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14790 for symbolic link (the string is the name linked to), or @code{nil}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14791 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14792 For example, the first @samp{.el} file in the @file{lisp/} directory |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14793 is @file{abbrev.el}. Its name is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14794 @file{/usr/local/share/emacs/21.0.100/lisp/abbrev.el} and it is not a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14795 directory or a symbolic link. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14796 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14797 @need 1000 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14798 This is how @code{directory-files-and-attributes} lists that file and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14799 its attributes: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14801 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14802 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14803 ("/usr/local/share/emacs/21.0.100/lisp/abbrev.el" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14804 nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14805 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14806 1000 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14807 100 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14808 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14809 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14810 (15019 32380) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14811 (14883 48041) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14812 (15214 49336) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14813 11583 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14814 "-rw-rw-r--" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14815 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14816 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14817 t |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14818 341385 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14819 776) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14820 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14821 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14822 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14823 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14824 On the other hand, @file{mail/} is a directory within the @file{lisp/} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14825 directory. The beginning of its listing looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14826 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14827 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14828 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14829 ("/usr/local/share/emacs/21.0.100/lisp/mail" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14830 t |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14831 @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14832 ) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14833 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14834 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14835 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14836 (Look at the documentation of @code{file-attributes} to learn about |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14837 the different attributes. Bear in mind that the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14838 @code{file-attributes} function does not list the filename, so its |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14839 first element is @code{directory-files-and-attributes}'s second |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14840 element.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14841 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14842 We will want our new function, @code{files-in-below-directory}, to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14843 list the @samp{.el} files in the directory it is told to check, and in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14844 any directories below that directory. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14845 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14846 This gives us a hint on how to construct |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14847 @code{files-in-below-directory}: within a directory, the function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14848 should add @samp{.el} filenames to a list; and if, within a directory, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14849 the function comes upon a sub-directory, it should go into that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14850 sub-directory and repeat its actions. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14851 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14852 However, we should note that every directory contains a name that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14853 refers to itself, called @file{.}, (``dot'') and a name that refers to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14854 its parent directory, called @file{..} (``double dot''). (In |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14855 @file{/}, the root directory, @file{..} refers to itself, since |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14856 @file{/} has no parent.) Clearly, we do not want our |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14857 @code{files-in-below-directory} function to enter those directories, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14858 since they always lead us, directly or indirectly, to the current |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14859 directory. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14860 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14861 Consequently, our @code{files-in-below-directory} function must do |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14862 several tasks: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14863 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14864 @itemize @bullet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14865 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14866 Check to see whether it is looking at a filename that ends in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14867 @samp{.el}; and if so, add its name to a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14868 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14869 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14870 Check to see whether it is looking at a filename that is the name of a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14871 directory; and if so, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14872 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14873 @itemize @minus |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14874 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14875 Check to see whether it is looking at @file{.} or @file{..}; and if |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14876 so skip it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14877 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14878 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14879 Or else, go into that directory and repeat the process. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14880 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14881 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14882 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14883 Let's write a function definition to do these tasks. We will use a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14884 @code{while} loop to move from one filename to another within a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14885 directory, checking what needs to be done; and we will use a recursive |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14886 call to repeat the actions on each sub-directory. The recursive |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14887 pattern is `accumulate' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14888 (@pxref{Accumulate, , Recursive Pattern: @emph{accumulate}}), |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14889 using @code{append} as the combiner. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14890 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14891 @ignore |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14892 (directory-files "/usr/local/share/emacs/21.0.100/lisp/" t "\\.el$") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14893 (shell-command "find /usr/local/share/emacs/21.0.100/lisp/ -name '*.el'") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14894 @end ignore |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14895 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14896 @c /usr/local/share/emacs/21.0.100/lisp/ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14897 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14898 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14899 Here is the function: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14900 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14901 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14902 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14903 (defun files-in-below-directory (directory) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14904 "List the .el files in DIRECTORY and in its sub-directories." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14905 ;; Although the function will be used non-interactively, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14906 ;; it will be easier to test if we make it interactive. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14907 ;; The directory will have a name such as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14908 ;; "/usr/local/share/emacs/21.0.100/lisp/" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14909 (interactive "DDirectory name: ") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14910 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14911 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14912 (let (el-files-list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14913 (current-directory-list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14914 (directory-files-and-attributes directory t))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14915 ;; while we are in the current directory |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14916 (while current-directory-list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14917 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14918 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14919 (cond |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14920 ;; check to see whether filename ends in `.el' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14921 ;; and if so, append its name to a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14922 ((equal ".el" (substring (car (car current-directory-list)) -3)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14923 (setq el-files-list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14924 (cons (car (car current-directory-list)) el-files-list))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14925 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14926 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14927 ;; check whether filename is that of a directory |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14928 ((eq t (car (cdr (car current-directory-list)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14929 ;; decide whether to skip or recurse |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14930 (if |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14931 (equal (or "." "..") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14932 (substring (car (car current-directory-list)) -1)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14933 ;; then do nothing if filename is that of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14934 ;; current directory or parent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14935 () |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14936 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14937 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14938 ;; else descend into the directory and repeat the process |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14939 (setq el-files-list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14940 (append |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14941 (files-in-below-directory |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14942 (car (car current-directory-list))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14943 el-files-list))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14944 ;; move to the next filename in the list; this also |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14945 ;; shortens the list so the while loop eventually comes to an end |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14946 (setq current-directory-list (cdr current-directory-list))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14947 ;; return the filenames |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14948 el-files-list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14949 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14950 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14951 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14952 @c (files-in-below-directory "/usr/local/share/emacs/21.0.100/lisp/") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14953 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14954 The @code{files-in-below-directory} @code{directory-files} function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14955 takes one argument, the name of a directory. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14956 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14957 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14958 Thus, on my system, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14959 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14960 @c !!! 21.0.100 lisp sources location here |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14961 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14962 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14963 (length |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14964 (files-in-below-directory "/usr/local/share/emacs/21.0.100/lisp/")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14965 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14966 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14967 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14968 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14969 tells me that my version 21.0.100 Lisp sources directory contains 754 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14970 @samp{.el} files. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14971 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14972 @code{files-in-below-directory} returns a list in reverse alphabetical |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14973 order. An expression to sort the list in alphabetical order looks |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14974 like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14975 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14976 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14977 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14978 (sort |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14979 (files-in-below-directory "/usr/local/share/emacs/21.0.100/lisp/") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14980 'string-lessp) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14981 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14982 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14983 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14984 @ignore |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14985 (defun test () |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14986 "Test how long it takes to find lengths of all elisp defuns." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14987 (insert "\n" (current-time-string) "\n") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14988 (sit-for 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14989 (sort |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14990 (recursive-lengths-list-many-files |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14991 '("../lisp/macros.el" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14992 "../lisp/mailalias.el" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14993 "../lisp/makesum.el")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14994 '<) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14995 (insert (format "%s" (current-time-string)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14996 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14997 @end ignore |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14998 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
14999 @node Counting function definitions, , Files List, Prepare the data |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15000 @subsection Counting function definitions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15001 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15002 Our immediate goal is to generate a list that tells us how many |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15003 function definitions contain fewer than 10 words and symbols, how many |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15004 contain between 10 and 19 words and symbols, how many contain between |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15005 20 and 29 words and symbols, and so on. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15006 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15007 With a sorted list of numbers, this is easy: count how many elements |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15008 of the list are smaller than 10, then, after moving past the numbers |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15009 just counted, count how many are smaller than 20, then, after moving |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15010 past the numbers just counted, count how many are smaller than 30, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15011 so on. Each of the numbers, 10, 20, 30, 40, and the like, is one |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15012 larger than the top of that range. We can call the list of such |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15013 numbers the @code{top-of-ranges} list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15014 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15015 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15016 If we wished, we could generate this list automatically, but it is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15017 simpler to write a list manually. Here it is: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15018 @vindex top-of-ranges |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15019 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15020 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15021 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15022 (defvar top-of-ranges |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15023 '(10 20 30 40 50 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15024 60 70 80 90 100 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15025 110 120 130 140 150 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15026 160 170 180 190 200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15027 210 220 230 240 250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15028 260 270 280 290 300) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15029 "List specifying ranges for `defuns-per-range'.") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15030 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15031 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15032 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15033 To change the ranges, we edit this list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15034 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15035 Next, we need to write the function that creates the list of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15036 number of definitions within each range. Clearly, this function must |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15037 take the @code{sorted-lengths} and the @code{top-of-ranges} lists |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15038 as arguments. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15039 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15040 The @code{defuns-per-range} function must do two things again and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15041 again: it must count the number of definitions within a range |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15042 specified by the current top-of-range value; and it must shift to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15043 next higher value in the @code{top-of-ranges} list after counting the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15044 number of definitions in the current range. Since each of these |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15045 actions is repetitive, we can use @code{while} loops for the job. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15046 One loop counts the number of definitions in the range defined by the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15047 current top-of-range value, and the other loop selects each of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15048 top-of-range values in turn. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15049 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15050 Several entries of the @code{sorted-lengths} list are counted for each |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15051 range; this means that the loop for the @code{sorted-lengths} list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15052 will be inside the loop for the @code{top-of-ranges} list, like a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15053 small gear inside a big gear. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15054 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15055 The inner loop counts the number of definitions within the range. It |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15056 is a simple counting loop of the type we have seen before. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15057 (@xref{Incrementing Loop, , A loop with an incrementing counter}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15058 The true-or-false test of the loop tests whether the value from the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15059 @code{sorted-lengths} list is smaller than the current value of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15060 top of the range. If it is, the function increments the counter and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15061 tests the next value from the @code{sorted-lengths} list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15062 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15063 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15064 The inner loop looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15065 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15066 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15067 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15068 (while @var{length-element-smaller-than-top-of-range} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15069 (setq number-within-range (1+ number-within-range)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15070 (setq sorted-lengths (cdr sorted-lengths))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15071 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15072 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15073 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15074 The outer loop must start with the lowest value of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15075 @code{top-of-ranges} list, and then be set to each of the succeeding |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15076 higher values in turn. This can be done with a loop like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15077 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15078 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15079 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15080 (while top-of-ranges |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15081 @var{body-of-loop}@dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15082 (setq top-of-ranges (cdr top-of-ranges))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15083 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15084 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15085 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15086 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15087 Put together, the two loops look like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15088 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15089 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15090 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15091 (while top-of-ranges |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15092 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15093 ;; @r{Count the number of elements within the current range.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15094 (while @var{length-element-smaller-than-top-of-range} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15095 (setq number-within-range (1+ number-within-range)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15096 (setq sorted-lengths (cdr sorted-lengths))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15097 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15098 ;; @r{Move to next range.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15099 (setq top-of-ranges (cdr top-of-ranges))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15100 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15101 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15102 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15103 In addition, in each circuit of the outer loop, Emacs should record |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15104 the number of definitions within that range (the value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15105 @code{number-within-range}) in a list. We can use @code{cons} for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15106 this purpose. (@xref{cons, , @code{cons}}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15107 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15108 The @code{cons} function works fine, except that the list it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15109 constructs will contain the number of definitions for the highest |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15110 range at its beginning and the number of definitions for the lowest |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15111 range at its end. This is because @code{cons} attaches new elements |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15112 of the list to the beginning of the list, and since the two loops are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15113 working their way through the lengths' list from the lower end first, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15114 the @code{defuns-per-range-list} will end up largest number first. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15115 But we will want to print our graph with smallest values first and the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15116 larger later. The solution is to reverse the order of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15117 @code{defuns-per-range-list}. We can do this using the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15118 @code{nreverse} function, which reverses the order of a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15119 @findex nreverse |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15120 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15121 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15122 For example, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15123 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15124 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15125 (nreverse '(1 2 3 4)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15126 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15127 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15128 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15129 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15130 produces: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15131 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15132 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15133 (4 3 2 1) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15134 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15135 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15136 Note that the @code{nreverse} function is ``destructive''---that is, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15137 it changes the list to which it is applied; this contrasts with the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15138 @code{car} and @code{cdr} functions, which are non-destructive. In |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15139 this case, we do not want the original @code{defuns-per-range-list}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15140 so it does not matter that it is destroyed. (The @code{reverse} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15141 function provides a reversed copy of a list, leaving the original list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15142 as is.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15143 @findex reverse |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15144 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15145 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15146 Put all together, the @code{defuns-per-range} looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15147 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15148 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15149 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15150 (defun defuns-per-range (sorted-lengths top-of-ranges) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15151 "SORTED-LENGTHS defuns in each TOP-OF-RANGES range." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15152 (let ((top-of-range (car top-of-ranges)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15153 (number-within-range 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15154 defuns-per-range-list) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15155 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15156 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15157 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15158 ;; @r{Outer loop.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15159 (while top-of-ranges |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15160 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15161 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15162 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15163 ;; @r{Inner loop.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15164 (while (and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15165 ;; @r{Need number for numeric test.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15166 (car sorted-lengths) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15167 (< (car sorted-lengths) top-of-range)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15168 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15169 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15170 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15171 ;; @r{Count number of definitions within current range.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15172 (setq number-within-range (1+ number-within-range)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15173 (setq sorted-lengths (cdr sorted-lengths))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15174 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15175 ;; @r{Exit inner loop but remain within outer loop.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15176 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15177 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15178 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15179 (setq defuns-per-range-list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15180 (cons number-within-range defuns-per-range-list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15181 (setq number-within-range 0) ; @r{Reset count to zero.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15182 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15183 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15184 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15185 ;; @r{Move to next range.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15186 (setq top-of-ranges (cdr top-of-ranges)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15187 ;; @r{Specify next top of range value.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15188 (setq top-of-range (car top-of-ranges))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15189 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15190 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15191 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15192 ;; @r{Exit outer loop and count the number of defuns larger than} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15193 ;; @r{ the largest top-of-range value.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15194 (setq defuns-per-range-list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15195 (cons |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15196 (length sorted-lengths) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15197 defuns-per-range-list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15198 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15199 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15200 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15201 ;; @r{Return a list of the number of definitions within each range,} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15202 ;; @r{ smallest to largest.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15203 (nreverse defuns-per-range-list))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15204 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15205 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15206 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15207 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15208 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15209 The function is straightforward except for one subtle feature. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15210 true-or-false test of the inner loop looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15211 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15212 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15213 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15214 (and (car sorted-lengths) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15215 (< (car sorted-lengths) top-of-range)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15216 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15217 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15218 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15219 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15220 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15221 instead of like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15222 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15223 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15224 (< (car sorted-lengths) top-of-range) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15225 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15226 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15227 The purpose of the test is to determine whether the first item in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15228 @code{sorted-lengths} list is less than the value of the top of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15229 range. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15230 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15231 The simple version of the test works fine unless the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15232 @code{sorted-lengths} list has a @code{nil} value. In that case, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15233 @code{(car sorted-lengths)} expression function returns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15234 @code{nil}. The @code{<} function cannot compare a number to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15235 @code{nil}, which is an empty list, so Emacs signals an error and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15236 stops the function from attempting to continue to execute. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15237 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15238 The @code{sorted-lengths} list always becomes @code{nil} when the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15239 counter reaches the end of the list. This means that any attempt to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15240 use the @code{defuns-per-range} function with the simple version of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15241 the test will fail. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15242 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15243 We solve the problem by using the @code{(car sorted-lengths)} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15244 expression in conjunction with the @code{and} expression. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15245 @code{(car sorted-lengths)} expression returns a non-@code{nil} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15246 value so long as the list has at least one number within it, but |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15247 returns @code{nil} if the list is empty. The @code{and} expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15248 first evaluates the @code{(car sorted-lengths)} expression, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15249 if it is @code{nil}, returns false @emph{without} evaluating the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15250 @code{<} expression. But if the @code{(car sorted-lengths)} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15251 expression returns a non-@code{nil} value, the @code{and} expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15252 evaluates the @code{<} expression, and returns that value as the value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15253 of the @code{and} expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15254 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15255 @c colon in printed section title causes problem in Info cross reference |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15256 This way, we avoid an error. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15257 @iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15258 @xref{forward-paragraph, , @code{forward-paragraph}: a Goldmine of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15259 Functions}, for more information about @code{and}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15260 @end iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15261 @ifinfo |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15262 @xref{forward-paragraph}, for more information about @code{and}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15263 @end ifinfo |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15264 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15265 Here is a short test of the @code{defuns-per-range} function. First, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15266 evaluate the expression that binds (a shortened) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15267 @code{top-of-ranges} list to the list of values, then evaluate the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15268 expression for binding the @code{sorted-lengths} list, and then |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15269 evaluate the @code{defuns-per-range} function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15270 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15271 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15272 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15273 ;; @r{(Shorter list than we will use later.)} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15274 (setq top-of-ranges |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15275 '(110 120 130 140 150 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15276 160 170 180 190 200)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15277 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15278 (setq sorted-lengths |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15279 '(85 86 110 116 122 129 154 176 179 200 265 300 300)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15280 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15281 (defuns-per-range sorted-lengths top-of-ranges) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15282 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15283 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15284 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15285 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15286 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15287 The list returned looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15288 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15289 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15290 (2 2 2 0 0 1 0 2 0 0 4) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15291 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15292 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15293 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15294 Indeed, there are two elements of the @code{sorted-lengths} list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15295 smaller than 110, two elements between 110 and 119, two elements |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15296 between 120 and 129, and so on. There are four elements with a value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15297 of 200 or larger. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15298 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15299 @c The next step is to turn this numbers' list into a graph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15300 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15301 @node Readying a Graph, Emacs Initialization, Words in a defun, Top |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15302 @chapter Readying a Graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15303 @cindex Readying a graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15304 @cindex Graph prototype |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15305 @cindex Prototype graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15306 @cindex Body of graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15307 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15308 Our goal is to construct a graph showing the numbers of function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15309 definitions of various lengths in the Emacs lisp sources. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15310 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15311 As a practical matter, if you were creating a graph, you would |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15312 probably use a program such as @code{gnuplot} to do the job. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15313 (@code{gnuplot} is nicely integrated into GNU Emacs.) In this case, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15314 however, we create one from scratch, and in the process we will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15315 re-acquaint ourselves with some of what we learned before and learn |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15316 more. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15317 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15318 In this chapter, we will first write a simple graph printing function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15319 This first definition will be a @dfn{prototype}, a rapidly written |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15320 function that enables us to reconnoiter this unknown graph-making |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15321 territory. We will discover dragons, or find that they are myth. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15322 After scouting the terrain, we will feel more confident and enhance |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15323 the function to label the axes automatically. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15324 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15325 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15326 * Columns of a graph:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15327 * graph-body-print:: How to print the body of a graph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15328 * recursive-graph-body-print:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15329 * Printed Axes:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15330 * Line Graph Exercise:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15331 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15332 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15333 @node Columns of a graph, graph-body-print, Readying a Graph, Readying a Graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15334 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15335 @unnumberedsec Printing the Columns of a Graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15336 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15337 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15338 Since Emacs is designed to be flexible and work with all kinds of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15339 terminals, including character-only terminals, the graph will need to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15340 be made from one of the `typewriter' symbols. An asterisk will do; as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15341 we enhance the graph-printing function, we can make the choice of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15342 symbol a user option. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15343 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15344 We can call this function @code{graph-body-print}; it will take a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15345 @code{numbers-list} as its only argument. At this stage, we will not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15346 label the graph, but only print its body. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15347 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15348 The @code{graph-body-print} function inserts a vertical column of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15349 asterisks for each element in the @code{numbers-list}. The height of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15350 each line is determined by the value of that element of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15351 @code{numbers-list}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15352 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15353 Inserting columns is a repetitive act; that means that this function can |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15354 be written either with a @code{while} loop or recursively. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15355 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15356 Our first challenge is to discover how to print a column of asterisks. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15357 Usually, in Emacs, we print characters onto a screen horizontally, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15358 line by line, by typing. We have two routes we can follow: write our |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15359 own column-insertion function or discover whether one exists in Emacs. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15360 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15361 To see whether there is one in Emacs, we can use the @kbd{M-x apropos} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15362 command. This command is like the @kbd{C-h a} (command-apropos) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15363 command, except that the latter finds only those functions that are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15364 commands. The @kbd{M-x apropos} command lists all symbols that match |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15365 a regular expression, including functions that are not interactive. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15366 @findex apropos |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15367 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15368 What we want to look for is some command that prints or inserts |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15369 columns. Very likely, the name of the function will contain either |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15370 the word `print' or the word `insert' or the word `column'. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15371 Therefore, we can simply type @kbd{M-x apropos RET |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15372 print\|insert\|column RET} and look at the result. On my system, this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15373 command takes quite some time, and then produces a list of 79 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15374 functions and variables. Scanning down the list, the only function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15375 that looks as if it might do the job is @code{insert-rectangle}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15376 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15377 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15378 Indeed, this is the function we want; its documentation says: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15379 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15380 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15381 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15382 insert-rectangle: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15383 Insert text of RECTANGLE with upper left corner at point. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15384 RECTANGLE's first line is inserted at point, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15385 its second line is inserted at a point vertically under point, etc. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15386 RECTANGLE should be a list of strings. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15387 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15388 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15389 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15390 We can run a quick test, to make sure it does what we expect of it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15391 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15392 Here is the result of placing the cursor after the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15393 @code{insert-rectangle} expression and typing @kbd{C-u C-x C-e} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15394 (@code{eval-last-sexp}). The function inserts the strings |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15395 @samp{"first"}, @samp{"second"}, and @samp{"third"} at and below |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15396 point. Also the function returns @code{nil}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15397 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15398 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15399 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15400 (insert-rectangle '("first" "second" "third"))first |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15401 second |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15402 third |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15403 nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15404 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15405 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15406 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15407 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15408 Of course, we won't be inserting the text of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15409 @code{insert-rectangle} expression itself into the buffer in which we |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15410 are making the graph, but will call the function from our program. We |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15411 shall, however, have to make sure that point is in the buffer at the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15412 place where the @code{insert-rectangle} function will insert its |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15413 column of strings. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15414 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15415 If you are reading this in Info, you can see how this works by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15416 switching to another buffer, such as the @file{*scratch*} buffer, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15417 placing point somewhere in the buffer, typing @kbd{M-:}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15418 typing the @code{insert-rectangle} expression into the minibuffer at |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15419 the prompt, and then typing @key{RET}. This causes Emacs to evaluate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15420 the expression in the minibuffer, but to use as the value of point the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15421 position of point in the @file{*scratch*} buffer. (@kbd{M-:} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15422 is the keybinding for @code{eval-expression}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15423 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15424 We find when we do this that point ends up at the end of the last |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15425 inserted line---that is to say, this function moves point as a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15426 side-effect. If we were to repeat the command, with point at this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15427 position, the next insertion would be below and to the right of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15428 previous insertion. We don't want this! If we are going to make a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15429 bar graph, the columns need to be beside each other. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15430 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15431 So we discover that each cycle of the column-inserting @code{while} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15432 loop must reposition point to the place we want it, and that place |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15433 will be at the top, not the bottom, of the column. Moreover, we |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15434 remember that when we print a graph, we do not expect all the columns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15435 to be the same height. This means that the top of each column may be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15436 at a different height from the previous one. We cannot simply |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15437 reposition point to the same line each time, but moved over to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15438 right---or perhaps we can@dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15439 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15440 We are planning to make the columns of the bar graph out of asterisks. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15441 The number of asterisks in the column is the number specified by the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15442 current element of the @code{numbers-list}. We need to construct a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15443 list of asterisks of the right length for each call to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15444 @code{insert-rectangle}. If this list consists solely of the requisite |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15445 number of asterisks, then we will have position point the right number |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15446 of lines above the base for the graph to print correctly. This could |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15447 be difficult. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15448 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15449 Alternatively, if we can figure out some way to pass |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15450 @code{insert-rectangle} a list of the same length each time, then we |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15451 can place point on the same line each time, but move it over one |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15452 column to the right for each new column. If we do this, however, some |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15453 of the entries in the list passed to @code{insert-rectangle} must be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15454 blanks rather than asterisks. For example, if the maximum height of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15455 the graph is 5, but the height of the column is 3, then |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15456 @code{insert-rectangle} requires an argument that looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15457 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15458 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15459 (" " " " "*" "*" "*") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15460 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15461 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15462 This last proposal is not so difficult, so long as we can determine |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15463 the column height. There are two ways for us to specify the column |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15464 height: we can arbitrarily state what it will be, which would work |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15465 fine for graphs of that height; or we can search through the list of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15466 numbers and use the maximum height of the list as the maximum height |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15467 of the graph. If the latter operation were difficult, then the former |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15468 procedure would be easiest, but there is a function built into Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15469 that determines the maximum of its arguments. We can use that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15470 function. The function is called @code{max} and it returns the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15471 largest of all its arguments, which must be numbers. Thus, for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15472 example, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15473 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15474 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15475 (max 3 4 6 5 7 3) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15476 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15477 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15478 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15479 returns 7. (A corresponding function called @code{min} returns the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15480 smallest of all its arguments.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15481 @findex max |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15482 @findex min |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15483 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15484 However, we cannot simply call @code{max} on the @code{numbers-list}; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15485 the @code{max} function expects numbers as its argument, not a list of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15486 numbers. Thus, the following expression, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15487 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15488 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15489 (max '(3 4 6 5 7 3)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15490 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15491 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15492 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15493 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15494 produces the following error message; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15495 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15496 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15497 Wrong type of argument: number-or-marker-p, (3 4 6 5 7 3) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15498 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15499 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15500 @findex apply |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15501 We need a function that passes a list of arguments to a function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15502 This function is @code{apply}. This function `applies' its first |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15503 argument (a function) to its remaining arguments, the last of which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15504 may be a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15505 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15506 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15507 For example, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15508 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15509 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15510 (apply 'max 3 4 7 3 '(4 8 5)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15511 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15512 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15513 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15514 returns 8. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15515 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15516 (Incidentally, I don't know how you would learn of this function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15517 without a book such as this. It is possible to discover other |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15518 functions, like @code{search-forward} or @code{insert-rectangle}, by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15519 guessing at a part of their names and then using @code{apropos}. Even |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15520 though its base in metaphor is clear---`apply' its first argument to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15521 the rest---I doubt a novice would come up with that particular word |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15522 when using @code{apropos} or other aid. Of course, I could be wrong; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15523 after all, the function was first named by someone who had to invent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15524 it.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15525 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15526 The second and subsequent arguments to @code{apply} are optional, so |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15527 we can use @code{apply} to call a function and pass the elements of a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15528 list to it, like this, which also returns 8: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15529 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15530 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15531 (apply 'max '(4 8 5)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15532 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15533 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15534 This latter way is how we will use @code{apply}. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15535 @code{recursive-lengths-list-many-files} function returns a numbers' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15536 list to which we can apply @code{max} (we could also apply @code{max} to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15537 the sorted numbers' list; it does not matter whether the list is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15538 sorted or not.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15539 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15540 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15541 Hence, the operation for finding the maximum height of the graph is this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15542 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15543 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15544 (setq max-graph-height (apply 'max numbers-list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15545 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15546 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15547 Now we can return to the question of how to create a list of strings |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15548 for a column of the graph. Told the maximum height of the graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15549 and the number of asterisks that should appear in the column, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15550 function should return a list of strings for the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15551 @code{insert-rectangle} command to insert. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15552 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15553 Each column is made up of asterisks or blanks. Since the function is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15554 passed the value of the height of the column and the number of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15555 asterisks in the column, the number of blanks can be found by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15556 subtracting the number of asterisks from the height of the column. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15557 Given the number of blanks and the number of asterisks, two |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15558 @code{while} loops can be used to construct the list: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15559 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15560 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15561 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15562 ;;; @r{First version.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15563 (defun column-of-graph (max-graph-height actual-height) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15564 "Return list of strings that is one column of a graph." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15565 (let ((insert-list nil) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15566 (number-of-top-blanks |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15567 (- max-graph-height actual-height))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15568 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15569 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15570 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15571 ;; @r{Fill in asterisks.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15572 (while (> actual-height 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15573 (setq insert-list (cons "*" insert-list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15574 (setq actual-height (1- actual-height))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15575 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15576 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15577 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15578 ;; @r{Fill in blanks.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15579 (while (> number-of-top-blanks 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15580 (setq insert-list (cons " " insert-list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15581 (setq number-of-top-blanks |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15582 (1- number-of-top-blanks))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15583 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15584 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15585 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15586 ;; @r{Return whole list.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15587 insert-list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15588 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15589 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15590 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15591 If you install this function and then evaluate the following |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15592 expression you will see that it returns the list as desired: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15593 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15594 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15595 (column-of-graph 5 3) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15596 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15597 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15598 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15599 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15600 returns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15601 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15602 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15603 (" " " " "*" "*" "*") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15604 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15605 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15606 As written, @code{column-of-graph} contains a major flaw: the symbols |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15607 used for the blank and for the marked entries in the column are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15608 `hard-coded' as a space and asterisk. This is fine for a prototype, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15609 but you, or another user, may wish to use other symbols. For example, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15610 in testing the graph function, you many want to use a period in place |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15611 of the space, to make sure the point is being repositioned properly |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15612 each time the @code{insert-rectangle} function is called; or you might |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15613 want to substitute a @samp{+} sign or other symbol for the asterisk. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15614 You might even want to make a graph-column that is more than one |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15615 display column wide. The program should be more flexible. The way to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15616 do that is to replace the blank and the asterisk with two variables |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15617 that we can call @code{graph-blank} and @code{graph-symbol} and define |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15618 those variables separately. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15619 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15620 Also, the documentation is not well written. These considerations |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15621 lead us to the second version of the function: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15622 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15623 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15624 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15625 (defvar graph-symbol "*" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15626 "String used as symbol in graph, usually an asterisk.") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15627 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15628 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15629 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15630 (defvar graph-blank " " |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15631 "String used as blank in graph, usually a blank space. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15632 graph-blank must be the same number of columns wide |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15633 as graph-symbol.") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15634 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15635 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15636 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15637 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15638 (For an explanation of @code{defvar}, see |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15639 @ref{defvar, , Initializing a Variable with @code{defvar}}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15640 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15641 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15642 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15643 ;;; @r{Second version.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15644 (defun column-of-graph (max-graph-height actual-height) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15645 "Return MAX-GRAPH-HEIGHT strings; ACTUAL-HEIGHT are graph-symbols. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15646 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15647 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15648 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15649 The graph-symbols are contiguous entries at the end |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15650 of the list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15651 The list will be inserted as one column of a graph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15652 The strings are either graph-blank or graph-symbol." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15653 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15654 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15655 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15656 (let ((insert-list nil) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15657 (number-of-top-blanks |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15658 (- max-graph-height actual-height))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15659 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15660 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15661 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15662 ;; @r{Fill in @code{graph-symbols}.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15663 (while (> actual-height 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15664 (setq insert-list (cons graph-symbol insert-list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15665 (setq actual-height (1- actual-height))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15666 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15667 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15668 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15669 ;; @r{Fill in @code{graph-blanks}.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15670 (while (> number-of-top-blanks 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15671 (setq insert-list (cons graph-blank insert-list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15672 (setq number-of-top-blanks |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15673 (1- number-of-top-blanks))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15674 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15675 ;; @r{Return whole list.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15676 insert-list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15677 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15678 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15679 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15680 If we wished, we could rewrite @code{column-of-graph} a third time to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15681 provide optionally for a line graph as well as for a bar graph. This |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15682 would not be hard to do. One way to think of a line graph is that it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15683 is no more than a bar graph in which the part of each bar that is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15684 below the top is blank. To construct a column for a line graph, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15685 function first constructs a list of blanks that is one shorter than |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15686 the value, then it uses @code{cons} to attach a graph symbol to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15687 list; then it uses @code{cons} again to attach the `top blanks' to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15688 the list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15689 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15690 It is easy to see how to write such a function, but since we don't |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15691 need it, we will not do it. But the job could be done, and if it were |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15692 done, it would be done with @code{column-of-graph}. Even more |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15693 important, it is worth noting that few changes would have to be made |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15694 anywhere else. The enhancement, if we ever wish to make it, is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15695 simple. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15696 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15697 Now, finally, we come to our first actual graph printing function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15698 This prints the body of a graph, not the labels for the vertical and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15699 horizontal axes, so we can call this @code{graph-body-print}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15700 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15701 @node graph-body-print, recursive-graph-body-print, Columns of a graph, Readying a Graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15702 @section The @code{graph-body-print} Function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15703 @findex graph-body-print |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15704 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15705 After our preparation in the preceding section, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15706 @code{graph-body-print} function is straightforward. The function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15707 will print column after column of asterisks and blanks, using the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15708 elements of a numbers' list to specify the number of asterisks in each |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15709 column. This is a repetitive act, which means we can use a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15710 decrementing @code{while} loop or recursive function for the job. In |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15711 this section, we will write the definition using a @code{while} loop. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15712 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15713 The @code{column-of-graph} function requires the height of the graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15714 as an argument, so we should determine and record that as a local variable. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15715 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15716 This leads us to the following template for the @code{while} loop |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15717 version of this function: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15718 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15719 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15720 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15721 (defun graph-body-print (numbers-list) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15722 "@var{documentation}@dots{}" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15723 (let ((height @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15724 @dots{})) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15725 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15726 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15727 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15728 (while numbers-list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15729 @var{insert-columns-and-reposition-point} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15730 (setq numbers-list (cdr numbers-list))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15731 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15732 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15733 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15734 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15735 We need to fill in the slots of the template. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15736 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15737 Clearly, we can use the @code{(apply 'max numbers-list)} expression to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15738 determine the height of the graph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15739 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15740 The @code{while} loop will cycle through the @code{numbers-list} one |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15741 element at a time. As it is shortened by the @code{(setq numbers-list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15742 (cdr numbers-list))} expression, the @sc{car} of each instance of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15743 list is the value of the argument for @code{column-of-graph}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15744 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15745 At each cycle of the @code{while} loop, the @code{insert-rectangle} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15746 function inserts the list returned by @code{column-of-graph}. Since |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15747 the @code{insert-rectangle} function moves point to the lower right of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15748 the inserted rectangle, we need to save the location of point at the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15749 time the rectangle is inserted, move back to that position after the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15750 rectangle is inserted, and then move horizontally to the next place |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15751 from which @code{insert-rectangle} is called. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15752 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15753 If the inserted columns are one character wide, as they will be if |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15754 single blanks and asterisks are used, the repositioning command is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15755 simply @code{(forward-char 1)}; however, the width of a column may be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15756 greater than one. This means that the repositioning command should be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15757 written @code{(forward-char symbol-width)}. The @code{symbol-width} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15758 itself is the length of a @code{graph-blank} and can be found using |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15759 the expression @code{(length graph-blank)}. The best place to bind |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15760 the @code{symbol-width} variable to the value of the width of graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15761 column is in the varlist of the @code{let} expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15762 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15763 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15764 These considerations lead to the following function definition: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15765 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15766 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15767 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15768 (defun graph-body-print (numbers-list) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15769 "Print a bar graph of the NUMBERS-LIST. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15770 The numbers-list consists of the Y-axis values." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15771 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15772 (let ((height (apply 'max numbers-list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15773 (symbol-width (length graph-blank)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15774 from-position) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15775 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15776 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15777 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15778 (while numbers-list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15779 (setq from-position (point)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15780 (insert-rectangle |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15781 (column-of-graph height (car numbers-list))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15782 (goto-char from-position) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15783 (forward-char symbol-width) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15784 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15785 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15786 ;; @r{Draw graph column by column.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15787 (sit-for 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15788 (setq numbers-list (cdr numbers-list))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15789 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15790 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15791 ;; @r{Place point for X axis labels.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15792 (forward-line height) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15793 (insert "\n") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15794 )) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15795 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15796 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15797 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15798 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15799 The one unexpected expression in this function is the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15800 @w{@code{(sit-for 0)}} expression in the @code{while} loop. This |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15801 expression makes the graph printing operation more interesting to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15802 watch than it would be otherwise. The expression causes Emacs to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15803 `sit' or do nothing for a zero length of time and then redraw the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15804 screen. Placed here, it causes Emacs to redraw the screen column by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15805 column. Without it, Emacs would not redraw the screen until the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15806 function exits. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15807 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15808 We can test @code{graph-body-print} with a short list of numbers. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15809 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15810 @enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15811 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15812 Install @code{graph-symbol}, @code{graph-blank}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15813 @code{column-of-graph}, which are in |
41499
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
15814 @iftex |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
15815 @ref{Readying a Graph, , Readying a Graph}, |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
15816 @end iftex |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
15817 @ifinfo |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
15818 @ref{Columns of a graph}, |
f2ffeff1bf1e
Move @contents to the beginning of the file.
Eli Zaretskii <eliz@gnu.org>
parents:
41421
diff
changeset
|
15819 @end ifinfo |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15820 and @code{graph-body-print}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15821 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15822 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15823 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15824 Copy the following expression: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15825 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15826 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15827 (graph-body-print '(1 2 3 4 6 4 3 5 7 6 5 2 3)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15828 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15829 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15830 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15831 Switch to the @file{*scratch*} buffer and place the cursor where you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15832 want the graph to start. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15833 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15834 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15835 Type @kbd{M-:} (@code{eval-expression}). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15836 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15837 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15838 Yank the @code{graph-body-print} expression into the minibuffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15839 with @kbd{C-y} (@code{yank)}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15840 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15841 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15842 Press @key{RET} to evaluate the @code{graph-body-print} expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15843 @end enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15844 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15845 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15846 Emacs will print a graph like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15847 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15848 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15849 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15850 * |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15851 * ** |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15852 * **** |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15853 *** **** |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15854 ********* * |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15855 ************ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15856 ************* |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15857 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15858 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15859 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15860 @node recursive-graph-body-print, Printed Axes, graph-body-print, Readying a Graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15861 @section The @code{recursive-graph-body-print} Function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15862 @findex recursive-graph-body-print |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15863 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15864 The @code{graph-body-print} function may also be written recursively. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15865 The recursive solution is divided into two parts: an outside `wrapper' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15866 that uses a @code{let} expression to determine the values of several |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15867 variables that need only be found once, such as the maximum height of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15868 the graph, and an inside function that is called recursively to print |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15869 the graph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15870 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15871 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15872 The `wrapper' is uncomplicated: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15873 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15874 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15875 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15876 (defun recursive-graph-body-print (numbers-list) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15877 "Print a bar graph of the NUMBERS-LIST. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15878 The numbers-list consists of the Y-axis values." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15879 (let ((height (apply 'max numbers-list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15880 (symbol-width (length graph-blank)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15881 from-position) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15882 (recursive-graph-body-print-internal |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15883 numbers-list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15884 height |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15885 symbol-width))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15886 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15887 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15888 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15889 The recursive function is a little more difficult. It has four parts: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15890 the `do-again-test', the printing code, the recursive call, and the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15891 `next-step-expression'. The `do-again-test' is an @code{if} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15892 expression that determines whether the @code{numbers-list} contains |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15893 any remaining elements; if it does, the function prints one column of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15894 the graph using the printing code and calls itself again. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15895 function calls itself again according to the value produced by the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15896 `next-step-expression' which causes the call to act on a shorter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15897 version of the @code{numbers-list}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15898 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15899 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15900 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15901 (defun recursive-graph-body-print-internal |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15902 (numbers-list height symbol-width) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15903 "Print a bar graph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15904 Used within recursive-graph-body-print function." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15905 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15906 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15907 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15908 (if numbers-list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15909 (progn |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15910 (setq from-position (point)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15911 (insert-rectangle |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15912 (column-of-graph height (car numbers-list))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15913 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15914 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15915 (goto-char from-position) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15916 (forward-char symbol-width) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15917 (sit-for 0) ; @r{Draw graph column by column.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15918 (recursive-graph-body-print-internal |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15919 (cdr numbers-list) height symbol-width)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15920 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15921 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15922 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15923 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15924 After installation, this expression can be tested; here is a sample: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15925 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15926 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15927 (recursive-graph-body-print '(3 2 5 6 7 5 3 4 6 4 3 2 1)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15928 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15929 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15930 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15931 Here is what @code{recursive-graph-body-print} produces: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15932 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15933 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15934 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15935 * |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15936 ** * |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15937 **** * |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15938 **** *** |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15939 * ********* |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15940 ************ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15941 ************* |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15942 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15943 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15944 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15945 Either of these two functions, @code{graph-body-print} or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15946 @code{recursive-graph-body-print}, create the body of a graph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15947 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15948 @node Printed Axes, Line Graph Exercise, recursive-graph-body-print, Readying a Graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15949 @section Need for Printed Axes |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15950 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15951 A graph needs printed axes, so you can orient yourself. For a do-once |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15952 project, it may be reasonable to draw the axes by hand using Emacs' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15953 Picture mode; but a graph drawing function may be used more than once. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15954 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15955 For this reason, I have written enhancements to the basic |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15956 @code{print-graph-body} function that automatically print labels for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15957 the horizontal and vertical axes. Since the label printing functions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15958 do not contain much new material, I have placed their description in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15959 an appendix. @xref{Full Graph, , A Graph with Labelled Axes}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15960 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15961 @node Line Graph Exercise, , Printed Axes, Readying a Graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15962 @section Exercise |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15963 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15964 Write a line graph version of the graph printing functions. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15965 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15966 @node Emacs Initialization, Debugging, Readying a Graph, Top |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15967 @chapter Your @file{.emacs} File |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15968 @cindex @file{.emacs} file |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15969 @cindex Customizing your @file{.emacs} file |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15970 @cindex Initialization file |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15971 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15972 ``You don't have to like Emacs to like it'' -- this seemingly |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15973 paradoxical statement is the secret of GNU Emacs. The plain, `out of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15974 the box' Emacs is a generic tool. Most people who use it, customize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15975 it to suit themselves. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15976 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15977 GNU Emacs is mostly written in Emacs Lisp; this means that by writing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15978 expressions in Emacs Lisp you can change or extend Emacs. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15979 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15980 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15981 * Default Configuration:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15982 * Site-wide Init:: You can write site-wide init files. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15983 * defcustom:: Emacs will write code for you. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15984 * Beginning a .emacs File:: How to write a @code{.emacs file}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15985 * Text and Auto-fill:: Automatically wrap lines. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15986 * Mail Aliases:: Use abbreviations for email addresses. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15987 * Indent Tabs Mode:: Don't use tabs with @TeX{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15988 * Keybindings:: Create some personal keybindings. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15989 * Keymaps:: More about key binding. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15990 * Loading Files:: Load (i.e., evaluate) files automatically. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15991 * Autoload:: Make functions available. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15992 * Simple Extension:: Define a function; bind it to a key. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15993 * X11 Colors:: Colors in version 19 in X. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15994 * Miscellaneous:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15995 * Mode Line:: How to customize your mode line. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15996 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15997 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15998 @node Default Configuration, Site-wide Init, Emacs Initialization, Emacs Initialization |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
15999 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16000 @unnumberedsec Emacs' Default Configuration |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16001 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16002 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16003 There are those who appreciate Emacs' default configuration. After |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16004 all, Emacs starts you in C mode when you edit a C file, starts you in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16005 Fortran mode when you edit a Fortran file, and starts you in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16006 Fundamental mode when you edit an unadorned file. This all makes |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16007 sense, if you do not know who is going to use Emacs. Who knows what a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16008 person hopes to do with an unadorned file? Fundamental mode is the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16009 right default for such a file, just as C mode is the right default for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16010 editing C code. But when you do know who is going to use Emacs---you, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16011 yourself---then it makes sense to customize Emacs. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16012 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16013 For example, I seldom want Fundamental mode when I edit an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16014 otherwise undistinguished file; I want Text mode. This is why I |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16015 customize Emacs: so it suits me. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16016 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16017 You can customize and extend Emacs by writing or adapting a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16018 @file{~/.emacs} file. This is your personal initialization file; its |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16019 contents, written in Emacs Lisp, tell Emacs what to do.@footnote{You |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16020 may also add @file{.el} to @file{~/.emacs} and call it a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16021 @file{~/.emacs.el} file. In the past, you were forbidden to type the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16022 extra keystrokes that the name @file{~/.emacs.el} requires, but now |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16023 you may. The new format is consistent with the Emacs Lisp file |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16024 naming conventions; the old format saves typing.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16025 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16026 A @file{~/.emacs} file contains Emacs Lisp code. You can write this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16027 code yourself; or you can use Emacs' @code{customize} feature to write |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16028 the code for you. You can combine your own expressions and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16029 auto-written Customize expressions in your @file{.emacs} file. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16030 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16031 (I myself prefer to write my own expressions, except for those, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16032 particularly fonts, that I find easier to manipulate using the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16033 @code{customize} command. I combine the two methods.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16034 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16035 Most of this chapter is about writing expressions yourself. It |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16036 describes a simple @file{.emacs} file; for more information, see |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16037 @ref{Init File, , The Init File, emacs, The GNU Emacs Manual}, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16038 @ref{Init File, , The Init File, elisp, The GNU Emacs Lisp Reference |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16039 Manual}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16040 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16041 @node Site-wide Init, defcustom, Default Configuration, Emacs Initialization |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16042 @section Site-wide Initialization Files |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16043 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16044 @cindex @file{default.el} init file |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16045 @cindex @file{site-init.el} init file |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16046 @cindex @file{site-load.el} init file |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16047 In addition to your personal initialization file, Emacs automatically |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16048 loads various site-wide initialization files, if they exist. These |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16049 have the same form as your @file{.emacs} file, but are loaded by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16050 everyone. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16051 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16052 Two site-wide initialization files, @file{site-load.el} and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16053 @file{site-init.el}, are loaded into Emacs and then `dumped' if a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16054 `dumped' version of Emacs is created, as is most common. (Dumped |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16055 copies of Emacs load more quickly. However, once a file is loaded and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16056 dumped, a change to it does not lead to a change in Emacs unless you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16057 load it yourself or re-dump Emacs. @xref{Building Emacs, , Building |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16058 Emacs, elisp, The GNU Emacs Lisp Reference Manual}, and the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16059 @file{INSTALL} file.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16060 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16061 Three other site-wide initialization files are loaded automatically |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16062 each time you start Emacs, if they exist. These are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16063 @file{site-start.el}, which is loaded @emph{before} your @file{.emacs} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16064 file, and @file{default.el}, and the terminal type file, which are both |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16065 loaded @emph{after} your @file{.emacs} file. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16066 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16067 Settings and definitions in your @file{.emacs} file will overwrite |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16068 conflicting settings and definitions in a @file{site-start.el} file, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16069 if it exists; but the settings and definitions in a @file{default.el} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16070 or terminal type file will overwrite those in your @file{.emacs} file. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16071 (You can prevent interference from a terminal type file by setting |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16072 @code{term-file-prefix} to @code{nil}. @xref{Simple Extension, , A |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16073 Simple Extension}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16074 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16075 @c Rewritten to avoid overfull hbox. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16076 The @file{INSTALL} file that comes in the distribution contains |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16077 descriptions of the @file{site-init.el} and @file{site-load.el} files. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16078 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16079 The @file{loadup.el}, @file{startup.el}, and @file{loaddefs.el} files |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16080 control loading. These files are in the @file{lisp} directory of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16081 Emacs distribution and are worth perusing. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16082 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16083 The @file{loaddefs.el} file contains a good many suggestions as to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16084 what to put into your own @file{.emacs} file, or into a site-wide |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16085 initialization file. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16086 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16087 @node defcustom, Beginning a .emacs File, Site-wide Init, Emacs Initialization |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16088 @section Specifying Variables using @code{defcustom} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16089 @findex defcustom |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16090 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16091 You can specify variables using @code{defcustom} so that you and |
44899
ebddb2618c17
Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents:
43431
diff
changeset
|
16092 others can then use Emacs' @code{customize} feature to set their |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16093 values. (You cannot use @code{customize} to write function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16094 definitions; but you can write @code{defuns} in your @file{.emacs} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16095 file. Indeed, you can write any Lisp expression in your @file{.emacs} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16096 file.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16097 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16098 The @code{customize} feature depends on the @code{defcustom} special |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16099 form. Although you can use @code{defvar} or @code{setq} for variables |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16100 that users set, the @code{defcustom} special form is designed for the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16101 job. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16102 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16103 You can use your knowledge of @code{defvar} for writing the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16104 first three arguments for @code{defcustom}. The first argument to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16105 @code{defcustom} is the name of the variable. The second argument is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16106 the variable's initial value, if any; and this value is set only if |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16107 the value has not already been set. The third argument is the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16108 documentation. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16109 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16110 The fourth and subsequent arguments to @code{defcustom} specify types |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16111 and options; these are not featured in @code{defvar}. (These |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16112 arguments are optional.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16113 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16114 Each of these arguments consists of a keyword followed by a value. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16115 Each keyword starts with the character @code{:}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16116 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16117 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16118 For example, the customizable user option variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16119 @code{text-mode-hook} looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16120 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16121 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16122 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16123 (defcustom text-mode-hook nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16124 "Normal hook run when entering Text mode and many related modes." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16125 :type 'hook |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16126 :options '(turn-on-auto-fill flyspell-mode) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16127 :group 'data) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16128 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16129 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16130 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16131 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16132 The name of the variable is @code{text-mode-hook}; it has no default |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16133 value; and its documentation string tells you what it does. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16134 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16135 The @code{:type} keyword tells Emacs what kind of data |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16136 @code{text-mode-hook} should be set to and how to display the value in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16137 a Customization buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16138 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16139 The @code{:options} keyword specifies a suggested list of values for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16140 the variable. Currently, you can use @code{:options} only for a hook. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16141 The list is only a suggestion; it is not exclusive; a person who sets |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16142 the variable may set it to other values; the list shown following the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16143 @code{:options} keyword is intended to offer convenient choices to a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16144 user. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16145 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16146 Finally, the @code{:group} keyword tells the Emacs Customization |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16147 command in which group the variable is located. This tells where to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16148 find it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16149 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16150 For more information, see @ref{Customization, , Writing Customization |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16151 Definitions, elisp, The GNU Emacs Lisp Reference Manual}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16152 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16153 Consider @code{text-mode-hook} as an example. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16154 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16155 There are two ways to customize this variable. You can use the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16156 customization command or write the appropriate expressions yourself. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16157 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16158 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16159 Using the customization command, you can type: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16160 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16161 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16162 M-x customize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16163 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16164 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16165 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16166 and find that the group for editing files of data is called `data'. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16167 Enter that group. Text Mode Hook is the first member. You can click |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16168 on its various options to set the values. After you click on the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16169 button to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16170 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16171 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16172 Save for Future Sessions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16173 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16174 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16175 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16176 Emacs will write an expression into your @file{.emacs} file. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16177 It will look like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16178 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16179 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16180 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16181 (custom-set-variables |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16182 ;; custom-set-variables was added by Custom -- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16183 ;; don't edit or cut/paste it! |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16184 ;; Your init file should contain only one such instance. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16185 '(text-mode-hook (quote (turn-on-auto-fill text-mode-hook-identify)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16186 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16187 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16188 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16189 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16190 (The @code{text-mode-hook-identify} function tells |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16191 @code{toggle-text-mode-auto-fill} which buffers are in Text mode.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16192 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16193 In spite of the warning, you certainly may edit, cut, and paste the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16194 expression! I do all time. The purpose of the warning is to scare |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16195 those who do not know what they are doing, so they do not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16196 inadvertently generate an error. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16197 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16198 The @code{custom-set-variables} works somewhat differently than a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16199 @code{setq}. While I have never learned the differences, I do modify |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16200 the @code{custom-set-variables} expressions in my @file{.emacs} file |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16201 by hand: I make the changes in what appears to me to be a reasonable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16202 manner and have not had any problems. Others prefer to use the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16203 Customization command and let Emacs do the work for them. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16204 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16205 Another @code{custom-set-@dots{}} function is @code{custom-set-faces}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16206 This function sets the various font faces. Over time, I have set a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16207 considerable number of faces. Some of the time, I re-set them using |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16208 @code{customize}; other times, I simply edit the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16209 @code{custom-set-faces} expression in my @file{.emacs} file itself. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16210 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16211 The second way to customize your @code{text-mode-hook} is to set it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16212 yourself in your @file{.emacs} file using code that has nothing to do |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16213 with the @code{custom-set-@dots{}} functions. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16214 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16215 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16216 When you do this, and later use @code{customize}, you will see a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16217 message that says |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16218 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16219 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16220 this option has been changed outside the customize buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16221 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16222 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16223 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16224 This message is only a warning. If you click on the button to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16225 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16226 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16227 Save for Future Sessions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16228 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16229 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16230 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16231 Emacs will write a @code{custom-set-@dots{}} expression near the end |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16232 of your @file{.emacs} file that will be evaluated after your |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16233 hand-written expression. It will, therefore, overrule your |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16234 hand-written expression. No harm will be done. When you do this, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16235 however, be careful to remember which expression is active; if you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16236 forget, you may confuse yourself. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16237 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16238 So long as you remember where the values are set, you will have no |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16239 trouble. In any event, the values are always set in your |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16240 initialization file, which is usually called @file{.emacs}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16241 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16242 I myself use @code{customize} for hardly anything. Mostly, I write |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16243 expressions myself. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16244 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16245 @node Beginning a .emacs File, Text and Auto-fill, defcustom, Emacs Initialization |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16246 @section Beginning a @file{.emacs} File |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16247 @cindex @file{.emacs} file, beginning of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16248 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16249 When you start Emacs, it loads your @file{.emacs} file unless you tell |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16250 it not to by specifying @samp{-q} on the command line. (The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16251 @code{emacs -q} command gives you a plain, out-of-the-box Emacs.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16252 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16253 A @file{.emacs} file contains Lisp expressions. Often, these are no |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16254 more than expressions to set values; sometimes they are function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16255 definitions. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16256 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16257 @xref{Init File, , The Init File @file{~/.emacs}, emacs, The GNU Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16258 Manual}, for a short description of initialization files. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16259 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16260 This chapter goes over some of the same ground, but is a walk among |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16261 extracts from a complete, long-used @file{.emacs} file---my own. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16262 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16263 The first part of the file consists of comments: reminders to myself. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16264 By now, of course, I remember these things, but when I started, I did |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16265 not. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16266 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16267 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16268 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16269 ;;;; Bob's .emacs file |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16270 ; Robert J. Chassell |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16271 ; 26 September 1985 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16272 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16273 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16274 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16275 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16276 Look at that date! I started this file a long time ago. I have been |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16277 adding to it ever since. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16278 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16279 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16280 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16281 ; Each section in this file is introduced by a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16282 ; line beginning with four semicolons; and each |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16283 ; entry is introduced by a line beginning with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16284 ; three semicolons. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16285 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16286 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16287 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16288 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16289 This describes the usual conventions for comments in Emacs Lisp. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16290 Everything on a line that follows a semicolon is a comment. Two, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16291 three, and four semicolons are used as section and subsection |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16292 markers. (@xref{Comments, ,, elisp, The GNU Emacs Lisp Reference |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16293 Manual}, for more about comments.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16294 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16295 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16296 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16297 ;;;; The Help Key |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16298 ; Control-h is the help key; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16299 ; after typing control-h, type a letter to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16300 ; indicate the subject about which you want help. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16301 ; For an explanation of the help facility, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16302 ; type control-h two times in a row. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16303 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16304 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16305 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16306 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16307 Just remember: type @kbd{C-h} two times for help. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16308 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16309 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16310 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16311 ; To find out about any mode, type control-h m |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16312 ; while in that mode. For example, to find out |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16313 ; about mail mode, enter mail mode and then type |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16314 ; control-h m. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16315 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16316 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16317 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16318 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16319 `Mode help', as I call this, is very helpful. Usually, it tells you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16320 all you need to know. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16321 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16322 Of course, you don't need to include comments like these in your |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16323 @file{.emacs} file. I included them in mine because I kept forgetting |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16324 about Mode help or the conventions for comments---but I was able to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16325 remember to look here to remind myself. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16326 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16327 @node Text and Auto-fill, Mail Aliases, Beginning a .emacs File, Emacs Initialization |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16328 @section Text and Auto Fill Mode |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16329 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16330 Now we come to the part that `turns on' Text mode and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16331 Auto Fill mode. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16332 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16333 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16334 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16335 ;;; Text mode and Auto Fill mode |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16336 ; The next three lines put Emacs into Text mode |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16337 ; and Auto Fill mode, and are for writers who |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16338 ; want to start writing prose rather than code. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16339 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16340 (setq default-major-mode 'text-mode) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16341 (add-hook 'text-mode-hook 'text-mode-hook-identify) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16342 (add-hook 'text-mode-hook 'turn-on-auto-fill) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16343 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16344 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16345 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16346 Here is the first part of this @file{.emacs} file that does something |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16347 besides remind a forgetful human! |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16348 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16349 The first of the two lines in parentheses tells Emacs to turn on Text |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16350 mode when you find a file, @emph{unless} that file should go into some |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16351 other mode, such as C mode. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16352 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16353 @cindex Per-buffer, local variables list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16354 @cindex Local variables list, per-buffer, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16355 @cindex Automatic mode selection |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16356 @cindex Mode selection, automatic |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16357 When Emacs reads a file, it looks at the extension to the file name, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16358 if any. (The extension is the part that comes after a @samp{.}.) If |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16359 the file ends with a @samp{.c} or @samp{.h} extension then Emacs turns |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16360 on C mode. Also, Emacs looks at first nonblank line of the file; if |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16361 the line says @w{@samp{-*- C -*-}}, Emacs turns on C mode. Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16362 possesses a list of extensions and specifications that it uses |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16363 automatically. In addition, Emacs looks near the last page for a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16364 per-buffer, ``local variables list'', if any. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16365 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16366 @ifinfo |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16367 @xref{Choosing Modes, , How Major Modes are Chosen, emacs, The GNU |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16368 Emacs Manual}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16369 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16370 @xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16371 Manual}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16372 @end ifinfo |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16373 @iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16374 See sections ``How Major Modes are Chosen'' and ``Local Variables in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16375 Files'' in @cite{The GNU Emacs Manual}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16376 @end iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16377 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16378 Now, back to the @file{.emacs} file. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16379 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16380 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16381 Here is the line again; how does it work? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16382 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16383 @cindex Text Mode turned on |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16384 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16385 (setq default-major-mode 'text-mode) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16386 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16387 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16388 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16389 This line is a short, but complete Emacs Lisp expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16390 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16391 We are already familiar with @code{setq}. It sets the following variable, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16392 @code{default-major-mode}, to the subsequent value, which is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16393 @code{text-mode}. The single quote mark before @code{text-mode} tells |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16394 Emacs to deal directly with the @code{text-mode} variable, not with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16395 whatever it might stand for. @xref{set & setq, , Setting the Value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16396 a Variable}, for a reminder of how @code{setq} works. The main point |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16397 is that there is no difference between the procedure you use to set |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16398 a value in your @file{.emacs} file and the procedure you use anywhere |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16399 else in Emacs. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16400 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16401 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16402 Here are the next two lines: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16403 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16404 @cindex Auto Fill mode turned on |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16405 @findex add-hook |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16406 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16407 (add-hook 'text-mode-hook 'text-mode-hook-identify) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16408 (add-hook 'text-mode-hook 'turn-on-auto-fill) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16409 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16410 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16411 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16412 In these two lines, the @code{add-hook} command first adds |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16413 @code{text-mode-hook-identify} to the variable called |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16414 @code{text-mode-hook} and then adds @code{turn-on-auto-fill} to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16415 variable. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16416 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16417 @code{turn-on-auto-fill} is the name of a program, that, you guessed |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16418 it!, turns on Auto Fill mode. @code{text-mode-hook-identify} is a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16419 function that tells @code{toggle-text-mode-auto-fill} which buffers |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16420 are in Text mode. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16421 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16422 Every time Emacs turns on Text mode, Emacs runs the commands `hooked' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16423 onto Text mode. So every time Emacs turns on Text mode, Emacs also |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16424 turns on Auto Fill mode. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16425 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16426 In brief, the first line causes Emacs to enter Text mode when you edit |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16427 a file, unless the file name extension, first non-blank line, or local |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16428 variables tell Emacs otherwise. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16429 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16430 Text mode among other actions, sets the syntax table to work |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16431 conveniently for writers. In Text mode, Emacs considers an apostrophe |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16432 as part of a word like a letter; but Emacs does not consider a period |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16433 or a space as part of a word. Thus, @kbd{M-f} moves you over |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16434 @samp{it's}. On the other hand, in C mode, @kbd{M-f} stops just after |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16435 the @samp{t} of @samp{it's}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16436 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16437 The second and third lines causes Emacs to turn on Auto Fill mode when |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16438 it turns on Text mode. In Auto Fill mode, Emacs automatically breaks |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16439 a line that is too wide and brings the excessively wide part of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16440 line down to the next line. Emacs breaks lines between words, not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16441 within them. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16442 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16443 When Auto Fill mode is turned off, lines continue to the right as you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16444 type them. Depending on how you set the value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16445 @code{truncate-lines}, the words you type either disappear off the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16446 right side of the screen, or else are shown, in a rather ugly and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16447 unreadable manner, as a continuation line on the screen. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16448 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16449 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16450 In addition, in this part of my @file{.emacs} file, I tell the Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16451 fill commands to insert two spaces after a colon: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16452 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16453 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16454 (setq colon-double-space t) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16455 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16456 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16457 @node Mail Aliases, Indent Tabs Mode, Text and Auto-fill, Emacs Initialization |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16458 @section Mail Aliases |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16459 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16460 Here is a @code{setq} that `turns on' mail aliases, along with more |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16461 reminders. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16462 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16463 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16464 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16465 ;;; Mail mode |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16466 ; To enter mail mode, type `C-x m' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16467 ; To enter RMAIL (for reading mail), |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16468 ; type `M-x rmail' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16469 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16470 (setq mail-aliases t) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16471 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16472 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16473 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16474 @cindex Mail aliases |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16475 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16476 This @code{setq} command sets the value of the variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16477 @code{mail-aliases} to @code{t}. Since @code{t} means true, the line |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16478 says, in effect, ``Yes, use mail aliases.'' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16479 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16480 Mail aliases are convenient short names for long email addresses or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16481 for lists of email addresses. The file where you keep your `aliases' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16482 is @file{~/.mailrc}. You write an alias like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16483 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16484 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16485 alias geo george@@foobar.wiz.edu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16486 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16487 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16488 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16489 When you write a message to George, address it to @samp{geo}; the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16490 mailer will automatically expand @samp{geo} to the full address. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16491 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16492 @node Indent Tabs Mode, Keybindings, Mail Aliases, Emacs Initialization |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16493 @section Indent Tabs Mode |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16494 @cindex Tabs, preventing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16495 @findex indent-tabs-mode |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16496 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16497 By default, Emacs inserts tabs in place of multiple spaces when it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16498 formats a region. (For example, you might indent many lines of text |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16499 all at once with the @code{indent-region} command.) Tabs look fine on |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16500 a terminal or with ordinary printing, but they produce badly indented |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16501 output when you use @TeX{} or Texinfo since @TeX{} ignores tabs. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16502 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16503 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16504 The following turns off Indent Tabs mode: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16505 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16506 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16507 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16508 ;;; Prevent Extraneous Tabs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16509 (setq-default indent-tabs-mode nil) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16510 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16511 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16512 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16513 Note that this line uses @code{setq-default} rather than the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16514 @code{setq} command that we have seen before. The @code{setq-default} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16515 command sets values only in buffers that do not have their own local |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16516 values for the variable. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16517 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16518 @ifinfo |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16519 @xref{Just Spaces, , Tabs vs. Spaces, emacs, The GNU Emacs Manual}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16520 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16521 @xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16522 Manual}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16523 @end ifinfo |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16524 @iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16525 See sections ``Tabs vs.@: Spaces'' and ``Local Variables in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16526 Files'' in @cite{The GNU Emacs Manual}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16527 @end iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16528 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16529 @node Keybindings, Keymaps, Indent Tabs Mode, Emacs Initialization |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16530 @section Some Keybindings |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16531 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16532 Now for some personal keybindings: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16533 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16534 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16535 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16536 ;;; Compare windows |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16537 (global-set-key "\C-cw" 'compare-windows) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16538 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16539 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16540 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16541 @findex compare-windows |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16542 @code{compare-windows} is a nifty command that compares the text in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16543 your current window with text in the next window. It makes the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16544 comparison by starting at point in each window, moving over text in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16545 each window as far as they match. I use this command all the time. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16546 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16547 This also shows how to set a key globally, for all modes. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16548 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16549 @cindex Setting a key globally |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16550 @cindex Global set key |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16551 @cindex Key setting globally |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16552 @findex global-set-key |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16553 The command is @code{global-set-key}. It is followed by the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16554 keybinding. In a @file{.emacs} file, the keybinding is written as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16555 shown: @code{\C-c} stands for `control-c', which means `press the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16556 control key and the @kbd{c} key at the same time'. The @code{w} means |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16557 `press the @kbd{w} key'. The keybinding is surrounded by double |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16558 quotation marks. In documentation, you would write this as @kbd{C-c |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16559 w}. (If you were binding a @key{META} key, such as @kbd{M-c}, rather |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16560 than a @key{CTL} key, you would write @code{\M-c}. @xref{Init |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16561 Rebinding, , Rebinding Keys in Your Init File, emacs, The GNU Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16562 Manual}, for details.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16563 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16564 The command invoked by the keys is @code{compare-windows}. Note that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16565 @code{compare-windows} is preceded by a single quote; otherwise, Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16566 would first try to evaluate the symbol to determine its value. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16567 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16568 These three things, the double quotation marks, the backslash before |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16569 the @samp{C}, and the single quote mark are necessary parts of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16570 keybinding that I tend to forget. Fortunately, I have come to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16571 remember that I should look at my existing @file{.emacs} file, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16572 adapt what is there. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16573 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16574 As for the keybinding itself: @kbd{C-c w}. This combines the prefix |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16575 key, @kbd{C-c}, with a single character, in this case, @kbd{w}. This |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16576 set of keys, @kbd{C-c} followed by a single character, is strictly |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16577 reserved for individuals' own use. (I call these `own' keys, since |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16578 these are for my own use.) You should always be able to create such a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16579 keybinding for your own use without stomping on someone else's |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16580 keybinding. If you ever write an extension to Emacs, please avoid |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16581 taking any of these keys for public use. Create a key like @kbd{C-c |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16582 C-w} instead. Otherwise, we will run out of `own' keys. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16583 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16584 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16585 Here is another keybinding, with a comment: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16586 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16587 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16588 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16589 ;;; Keybinding for `occur' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16590 ; I use occur a lot, so let's bind it to a key: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16591 (global-set-key "\C-co" 'occur) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16592 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16593 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16594 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16595 @findex occur |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16596 The @code{occur} command shows all the lines in the current buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16597 that contain a match for a regular expression. Matching lines are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16598 shown in a buffer called @file{*Occur*}. That buffer serves as a menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16599 to jump to occurrences. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16600 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16601 @findex global-unset-key |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16602 @cindex Unbinding key |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16603 @cindex Key unbinding |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16604 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16605 Here is how to unbind a key, so it does not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16606 work: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16607 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16608 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16609 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16610 ;;; Unbind `C-x f' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16611 (global-unset-key "\C-xf") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16612 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16613 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16614 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16615 There is a reason for this unbinding: I found I inadvertently typed |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16616 @w{@kbd{C-x f}} when I meant to type @kbd{C-x C-f}. Rather than find a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16617 file, as I intended, I accidentally set the width for filled text, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16618 almost always to a width I did not want. Since I hardly ever reset my |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16619 default width, I simply unbound the key. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16620 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16621 @findex list-buffers, @r{rebound} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16622 @findex buffer-menu, @r{bound to key} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16623 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16624 The following rebinds an existing key: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16625 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16626 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16627 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16628 ;;; Rebind `C-x C-b' for `buffer-menu' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16629 (global-set-key "\C-x\C-b" 'buffer-menu) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16630 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16631 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16632 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16633 By default, @kbd{C-x C-b} runs the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16634 @code{list-buffers} command. This command lists |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16635 your buffers in @emph{another} window. Since I |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16636 almost always want to do something in that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16637 window, I prefer the @code{buffer-menu} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16638 command, which not only lists the buffers, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16639 but moves point into that window. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16640 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16641 @node Keymaps, Loading Files, Keybindings, Emacs Initialization |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16642 @section Keymaps |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16643 @cindex Keymaps |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16644 @cindex Rebinding keys |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16645 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16646 Emacs uses @dfn{keymaps} to record which keys call which commands. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16647 When you use @code{global-set-key} to set the keybinding for a single |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16648 command in all parts of Emacs, you are specifying the keybinding in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16649 @code{current-global-map}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16650 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16651 Specific modes, such as C mode or Text mode, have their own keymaps; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16652 the mode-specific keymaps override the global map that is shared by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16653 all buffers. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16654 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16655 The @code{global-set-key} function binds, or rebinds, the global |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16656 keymap. For example, the following binds the key @kbd{C-x C-b} to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16657 function @code{buffer-menu}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16658 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16659 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16660 (global-set-key "\C-x\C-b" 'buffer-menu) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16661 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16662 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16663 Mode-specific keymaps are bound using the @code{define-key} function, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16664 which takes a specific keymap as an argument, as well as the key and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16665 the command. For example, my @file{.emacs} file contains the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16666 following expression to bind the @code{texinfo-insert-@@group} command |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16667 to @kbd{C-c C-c g}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16668 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16669 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16670 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16671 (define-key texinfo-mode-map "\C-c\C-cg" 'texinfo-insert-@@group) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16672 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16673 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16674 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16675 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16676 The @code{texinfo-insert-@@group} function itself is a little extension |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16677 to Texinfo mode that inserts @samp{@@group} into a Texinfo file. I |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16678 use this command all the time and prefer to type the three strokes |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16679 @kbd{C-c C-c g} rather than the six strokes @kbd{@@ g r o u p}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16680 (@samp{@@group} and its matching @samp{@@end group} are commands that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16681 keep all enclosed text together on one page; many multi-line examples |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16682 in this book are surrounded by @samp{@@group @dots{} @@end group}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16683 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16684 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16685 Here is the @code{texinfo-insert-@@group} function definition: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16686 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16687 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16688 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16689 (defun texinfo-insert-@@group () |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16690 "Insert the string @@group in a Texinfo buffer." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16691 (interactive) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16692 (beginning-of-line) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16693 (insert "@@group\n")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16694 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16695 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16696 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16697 (Of course, I could have used Abbrev mode to save typing, rather than |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16698 write a function to insert a word; but I prefer key strokes consistent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16699 with other Texinfo mode key bindings.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16700 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16701 You will see numerous @code{define-key} expressions in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16702 @file{loaddefs.el} as well as in the various mode libraries, such as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16703 @file{cc-mode.el} and @file{lisp-mode.el}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16704 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16705 @xref{Key Bindings, , Customizing Key Bindings, emacs, The GNU Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16706 Manual}, and @ref{Keymaps, , Keymaps, elisp, The GNU Emacs Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16707 Reference Manual}, for more information about keymaps. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16708 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16709 @node Loading Files, Autoload, Keymaps, Emacs Initialization |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16710 @section Loading Files |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16711 @cindex Loading files |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16712 @c findex load |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16713 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16714 Many people in the GNU Emacs community have written extensions to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16715 Emacs. As time goes by, these extensions are often included in new |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16716 releases. For example, the Calendar and Diary packages are now part |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16717 of the standard GNU Emacs. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16718 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16719 (Calc, which I consider a vital part of Emacs, would be part of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16720 standard distribution except that it was so large it was packaged |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16721 separately and no one has changed that.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16722 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16723 You can use a @code{load} command to evaluate a complete file and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16724 thereby install all the functions and variables in the file into Emacs. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16725 For example: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16726 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16727 @c (auto-compression-mode t) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16728 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16729 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16730 (load "~/emacs/slowsplit") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16731 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16732 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16733 This evaluates, i.e.@: loads, the @file{slowsplit.el} file or if it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16734 exists, the faster, byte compiled @file{slowsplit.elc} file from the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16735 @file{emacs} sub-directory of your home directory. The file contains |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16736 the function @code{split-window-quietly}, which John Robinson wrote in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16737 1989. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16738 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16739 The @code{split-window-quietly} function splits a window with the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16740 minimum of redisplay. I installed it in 1989 because it worked well |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16741 with the slow 1200 baud terminals I was then using. Nowadays, I only |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16742 occasionally come across such a slow connection, but I continue to use |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16743 the function because I like the way it leaves the bottom half of a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16744 buffer in the lower of the new windows and the top half in the upper |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16745 window. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16746 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16747 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16748 To replace the key binding for the default |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16749 @code{split-window-vertically}, you must also unset that key and bind |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16750 the keys to @code{split-window-quietly}, like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16751 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16752 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16753 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16754 (global-unset-key "\C-x2") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16755 (global-set-key "\C-x2" 'split-window-quietly) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16756 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16757 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16758 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16759 @vindex load-path |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16760 If you load many extensions, as I do, then instead of specifying the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16761 exact location of the extension file, as shown above, you can specify |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16762 that directory as part of Emacs' @code{load-path}. Then, when Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16763 loads a file, it will search that directory as well as its default |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16764 list of directories. (The default list is specified in @file{paths.h} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16765 when Emacs is built.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16766 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16767 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16768 The following command adds your @file{~/emacs} directory to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16769 existing load path: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16770 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16771 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16772 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16773 ;;; Emacs Load Path |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16774 (setq load-path (cons "~/emacs" load-path)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16775 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16776 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16777 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16778 Incidentally, @code{load-library} is an interactive interface to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16779 @code{load} function. The complete function looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16780 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16781 @findex load-library |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16782 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16783 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16784 (defun load-library (library) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16785 "Load the library named LIBRARY. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16786 This is an interface to the function `load'." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16787 (interactive "sLoad library: ") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16788 (load library)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16789 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16790 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16791 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16792 The name of the function, @code{load-library}, comes from the use of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16793 `library' as a conventional synonym for `file'. The source for the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16794 @code{load-library} command is in the @file{files.el} library. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16795 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16796 Another interactive command that does a slightly different job is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16797 @code{load-file}. @xref{Lisp Libraries, , Libraries of Lisp Code for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16798 Emacs, emacs, The GNU Emacs Manual}, for information on the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16799 distinction between @code{load-library} and this command. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16801 @node Autoload, Simple Extension, Loading Files, Emacs Initialization |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16802 @section Autoloading |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16803 @findex autoload |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16804 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16805 Instead of installing a function by loading the file that contains it, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16806 or by evaluating the function definition, you can make the function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16807 available but not actually install it until it is first called. This |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16808 is called @dfn{autoloading}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16809 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16810 When you execute an autoloaded function, Emacs automatically evaluates |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16811 the file that contains the definition, and then calls the function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16812 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16813 Emacs starts quicker with autoloaded functions, since their libraries |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16814 are not loaded right away; but you need to wait a moment when you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16815 first use such a function, while its containing file is evaluated. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16816 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16817 Rarely used functions are frequently autoloaded. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16818 @file{loaddefs.el} library contains hundreds of autoloaded functions, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16819 from @code{bookmark-set} to @code{wordstar-mode}. Of course, you may |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16820 come to use a `rare' function frequently. When you do, you should |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16821 load that function's file with a @code{load} expression in your |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16822 @file{.emacs} file. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16823 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16824 In my @file{.emacs} file for Emacs version 21, I load 12 libraries |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16825 that contain functions that would otherwise be autoloaded. (Actually, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16826 it would have been better to include these files in my `dumped' Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16827 when I built it, but I forgot. @xref{Building Emacs, , Building |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16828 Emacs, elisp, The GNU Emacs Lisp Reference Manual}, and the @file{INSTALL} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16829 file for more about dumping.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16830 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16831 You may also want to include autoloaded expressions in your @file{.emacs} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16832 file. @code{autoload} is a built-in function that takes up to five |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16833 arguments, the final three of which are optional. The first argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16834 is the name of the function to be autoloaded; the second is the name |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16835 of the file to be loaded. The third argument is documentation for the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16836 function, and the fourth tells whether the function can be called |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16837 interactively. The fifth argument tells what type of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16838 object---@code{autoload} can handle a keymap or macro as well as a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16839 function (the default is a function). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16840 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16841 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16842 Here is a typical example: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16843 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16844 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16845 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16846 (autoload 'html-helper-mode |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16847 "html-helper-mode" "Edit HTML documents" t) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16848 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16849 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16850 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16851 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16852 (@code{html-helper-mode} is an alternative to @code{html-mode}, which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16853 is a standard part of the distribution). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16854 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16855 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16856 This expression autoloads the @code{html-helper-mode} function. It |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16857 takes it from the @file{html-helper-mode.el} file (or from the byte |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16858 compiled file @file{html-helper-mode.elc}, if it exists.) The file |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16859 must be located in a directory specified by @code{load-path}. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16860 documentation says that this is a mode to help you edit documents |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16861 written in the HyperText Markup Language. You can call this mode |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16862 interactively by typing @kbd{M-x html-helper-mode}. (You need to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16863 duplicate the function's regular documentation in the autoload |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16864 expression because the regular function is not yet loaded, so its |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16865 documentation is not available.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16866 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16867 @xref{Autoload, , Autoload, elisp, The GNU Emacs Lisp Reference |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16868 Manual}, for more information. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16869 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16870 @node Simple Extension, X11 Colors, Autoload, Emacs Initialization |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16871 @section A Simple Extension: @code{line-to-top-of-window} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16872 @findex line-to-top-of-window |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16873 @cindex Simple extension in @file{.emacs} file |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16874 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16875 Here is a simple extension to Emacs that moves the line point is on to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16876 the top of the window. I use this all the time, to make text easier |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16877 to read. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16878 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16879 You can put the following code into a separate file and then load it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16880 from your @file{.emacs} file, or you can include it within your |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16881 @file{.emacs} file. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16882 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16883 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16884 Here is the definition: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16885 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16886 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16887 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16888 ;;; Line to top of window; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16889 ;;; replace three keystroke sequence C-u 0 C-l |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16890 (defun line-to-top-of-window () |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16891 "Move the line point is on to top of window." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16892 (interactive) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16893 (recenter 0)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16894 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16895 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16896 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16897 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16898 Now for the keybinding. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16899 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16900 Nowadays, function keys as well as mouse button events and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16901 non-@sc{ascii} characters are written within square brackets, without |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16902 quotation marks. (In Emacs version 18 and before, you had to write |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16903 different function key bindings for each different make of terminal.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16904 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16905 I bind @code{line-to-top-of-window} to my @key{F6} function key like |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16906 this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16907 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16908 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16909 (global-set-key [f6] 'line-to-top-of-window) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16910 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16911 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16912 For more information, see @ref{Init Rebinding, , Rebinding Keys in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16913 Your Init File, emacs, The GNU Emacs Manual}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16914 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16915 @cindex Conditional 'twixt two versions of Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16916 @cindex Version of Emacs, choosing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16917 @cindex Emacs version, choosing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16918 If you run two versions of GNU Emacs, such as versions 20 and 21, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16919 use one @file{.emacs} file, you can select which code to evaluate with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16920 the following conditional: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16921 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16922 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16923 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16924 (cond |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16925 ((string-equal (number-to-string 20) (substring (emacs-version) 10 12)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16926 ;; evaluate version 20 code |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16927 ( @dots{} )) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16928 ((string-equal (number-to-string 21) (substring (emacs-version) 10 12)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16929 ;; evaluate version 21 code |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16930 ( @dots{} ))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16931 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16932 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16933 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16934 For example, in contrast to version 20, version 21 blinks its cursor |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16935 by default. I hate such blinking, as well as some other features in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16936 version 21, so I placed the following in my @file{.emacs} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16937 file@footnote{When I start instances of Emacs that do not load my |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16938 @file{.emacs} file or any site file, I also turn off blinking: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16939 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16940 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16941 emacs -q --no-site-file -eval '(blink-cursor-mode nil)' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16942 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16943 }: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16944 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16945 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16946 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16947 (if (string-equal "21" (substring (emacs-version) 10 12)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16948 (progn |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16949 (blink-cursor-mode 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16950 ;; Insert newline when you press `C-n' (next-line) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16951 ;; at the end of the buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16952 (setq next-line-add-newlines t) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16953 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16954 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16955 ;; Turn on image viewing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16956 (auto-image-file-mode t) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16957 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16958 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16959 ;; Turn on menu bar (this bar has text) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16960 ;; (Use numeric argument to turn on) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16961 (menu-bar-mode 1) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16962 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16963 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16964 ;; Turn off tool bar (this bar has icons) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16965 ;; (Use numeric argument to turn on) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16966 (tool-bar-mode nil) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16967 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16968 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16969 ;; Turn off tooltip mode for tool bar |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16970 ;; (This mode causes icon explanations to pop up) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16971 ;; (Use numeric argument to turn on) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16972 (tooltip-mode nil) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16973 ;; If tooltips turned on, make tips appear promptly |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16974 (setq tooltip-delay 0.1) ; default is one second |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16975 )) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16976 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16977 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16978 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16979 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16980 (You will note that instead of typing @code{(number-to-string 21)}, I |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16981 decided to save typing and wrote `21' as a string, @code{"21"}, rather |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16982 than convert it from an integer to a string. In this instance, this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16983 expression is better than the longer, but more general |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16984 @code{(number-to-string 21)}. However, if you do not know ahead of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16985 time what type of information will be returned, then the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16986 @code{number-to-string} function will be needed.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16987 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16988 @node X11 Colors, Miscellaneous, Simple Extension, Emacs Initialization |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16989 @section X11 Colors |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16990 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16991 You can specify colors when you use Emacs with the MIT X Windowing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16992 system. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16993 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16994 I dislike the default colors and specify my own. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16995 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16996 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16997 Here are the expressions in my @file{.emacs} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16998 file that set values: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
16999 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17000 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17001 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17002 ;; Set cursor color |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17003 (set-cursor-color "white") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17004 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17005 ;; Set mouse color |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17006 (set-mouse-color "white") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17007 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17008 ;; Set foreground and background |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17009 (set-foreground-color "white") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17010 (set-background-color "darkblue") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17011 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17012 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17013 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17014 ;;; Set highlighting colors for isearch and drag |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17015 (set-face-foreground 'highlight "white") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17016 (set-face-background 'highlight "blue") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17017 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17018 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17019 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17020 (set-face-foreground 'region "cyan") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17021 (set-face-background 'region "blue") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17022 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17023 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17024 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17025 (set-face-foreground 'secondary-selection "skyblue") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17026 (set-face-background 'secondary-selection "darkblue") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17027 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17028 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17029 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17030 ;; Set calendar highlighting colors |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17031 (setq calendar-load-hook |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17032 '(lambda () |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17033 (set-face-foreground 'diary-face "skyblue") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17034 (set-face-background 'holiday-face "slate blue") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17035 (set-face-foreground 'holiday-face "white"))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17036 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17037 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17038 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17039 The various shades of blue soothe my eye and prevent me from seeing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17040 the screen flicker. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17041 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17042 Alternatively, I could have set my specifications in various X |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17043 initialization files. For example, I could set the foreground, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17044 background, cursor, and pointer (i.e., mouse) colors in my |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17045 @file{~/.Xresources} file like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17046 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17047 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17048 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17049 Emacs*foreground: white |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17050 Emacs*background: darkblue |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17051 Emacs*cursorColor: white |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17052 Emacs*pointerColor: white |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17053 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17054 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17055 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17056 In any event, since it is not part of Emacs, I set the root color of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17057 my X window in my @file{~/.xinitrc} file, like this@footnote{I |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17058 occasionally run more modern window managers, such as Sawfish with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17059 GNOME, Enlightenment, SCWM, or KDE; in those cases, I often specify an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17060 image rather than a plain color.}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17061 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17062 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17063 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17064 # I use TWM for window manager. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17065 xsetroot -solid Navy -fg white & |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17066 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17067 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17068 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17069 @node Miscellaneous, Mode Line, X11 Colors, Emacs Initialization |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17070 @section Miscellaneous Settings for a @file{.emacs} File |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17071 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17072 Here are a few miscellaneous settings: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17073 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17074 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17075 @itemize @minus |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17076 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17077 Set the shape and color of the mouse cursor: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17078 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17079 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17080 ; Cursor shapes are defined in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17081 ; `/usr/include/X11/cursorfont.h'; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17082 ; for example, the `target' cursor is number 128; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17083 ; the `top_left_arrow' cursor is number 132. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17084 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17085 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17086 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17087 (let ((mpointer (x-get-resource "*mpointer" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17088 "*emacs*mpointer"))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17089 ;; If you have not set your mouse pointer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17090 ;; then set it, otherwise leave as is: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17091 (if (eq mpointer nil) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17092 (setq mpointer "132")) ; top_left_arrow |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17093 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17094 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17095 (setq x-pointer-shape (string-to-int mpointer)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17096 (set-mouse-color "white")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17097 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17098 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17099 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17100 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17101 @node Mode Line, , Miscellaneous, Emacs Initialization |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17102 @section A Modified Mode Line |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17103 @vindex default-mode-line-format |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17104 @cindex Mode line format |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17105 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17106 Finally, a feature I really like: a modified mode line. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17107 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17108 When I work over a network, I forget which machine I am using. Also, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17109 I tend to I lose track of where I am, and which line point is on. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17110 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17111 So I reset my mode line to look like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17112 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17113 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17114 -:-- foo.texi rattlesnake:/home/bob/ Line 1 (Texinfo Fill) Top |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17115 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17116 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17117 I am visiting a file called @file{foo.texi}, on my machine |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17118 @file{rattlesnake} in my @file{/home/bob} buffer. I am on line 1, in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17119 Texinfo mode, and am at the top of the buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17120 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17121 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17122 My @file{.emacs} file has a section that looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17123 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17124 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17125 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17126 ;; Set a Mode Line that tells me which machine, which directory, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17127 ;; and which line I am on, plus the other customary information. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17128 (setq default-mode-line-format |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17129 (quote |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17130 (#("-" 0 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17131 (help-echo |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17132 "mouse-1: select window, mouse-2: delete others ...")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17133 mode-line-mule-info |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17134 mode-line-modified |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17135 mode-line-frame-identification |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17136 " " |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17137 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17138 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17139 mode-line-buffer-identification |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17140 " " |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17141 (:eval (substring |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17142 (system-name) 0 (string-match "\\..+" (system-name)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17143 ":" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17144 default-directory |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17145 #(" " 0 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17146 (help-echo |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17147 "mouse-1: select window, mouse-2: delete others ...")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17148 (line-number-mode " Line %l ") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17149 global-mode-string |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17150 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17151 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17152 #(" %[(" 0 6 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17153 (help-echo |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17154 "mouse-1: select window, mouse-2: delete others ...")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17155 (:eval (mode-line-mode-name)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17156 mode-line-process |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17157 minor-mode-alist |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17158 #("%n" 0 2 (help-echo "mouse-2: widen" local-map (keymap ...))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17159 ")%] " |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17160 (-3 . "%P") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17161 ;; "-%-" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17162 ))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17163 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17164 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17165 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17166 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17167 Here, I redefine the default mode line. Most of the parts are from |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17168 the original; but I make a few changes. I set the @emph{default} mode |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17169 line format so as to permit various modes, such as Info, to override |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17170 it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17171 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17172 Many elements in the list are self-explanatory: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17173 @code{mode-line-modified} is a variable that tells whether the buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17174 has been modified, @code{mode-name} tells the name of the mode, and so |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17175 on. However, the format looks complicated because of two features we |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17176 have not discussed. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17177 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17178 The first string in the mode line is a dash or hyphen, @samp{-}. In |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17179 the old days, it would have been specified simply as @code{"-"}. But |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17180 nowadays, Emacs can add properties to a string, such as highlighting |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17181 or, as in this case, a help feature. If you place your mouse cursor |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17182 over the hyphen, some help information appears (By default, you must |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17183 wait one second before the information appears. You can change that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17184 timing by changing the value of @code{tooltip-delay}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17185 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17186 @need 1000 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17187 The new string format has a special syntax: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17188 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17189 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17190 #("-" 0 1 (help-echo "mouse-1: select window, ...")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17191 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17192 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17193 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17194 The @code{#(} begins a list. The first element of the list is the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17195 string itself, just one @samp{-}. The second and third |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17196 elements specify the range over which the fourth element applies. A |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17197 range starts @emph{after} a character, so a zero means the range |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17198 starts just before the first character; a 1 means that the range ends |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17199 just after the first character. The third element is the property for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17200 the range. It consists of a property list, a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17201 property name, in this case, @samp{help-echo}, followed by a value, in this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17202 case, a string. The second, third, and fourth elements of this new |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17203 string format can be repeated. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17204 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17205 @xref{Text Props and Strings, , Text Properties in String, elisp, The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17206 GNU Emacs Lisp Reference Manual}, and see @ref{Mode Line Format, , Mode |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17207 Line Format, elisp, The GNU Emacs Lisp Reference Manual}, for more |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17208 information. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17209 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17210 @code{mode-line-buffer-identification} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17211 displays the current buffer name. It is a list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17212 beginning @code{(#("%12b" 0 4 @dots{}}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17213 The @code{#(} begins the list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17214 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17215 The @samp{"%12b"} displays the current buffer name, using the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17216 @code{buffer-name} function with which we are familiar; the `12' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17217 specifies the maximum number of characters that will be displayed. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17218 When a name has fewer characters, whitespace is added to fill out to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17219 this number. (Buffer names can and often should be longer than 12 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17220 characters; this length works well in a typical 80 column wide |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17221 window.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17222 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17223 @code{:eval} is a new feature in GNU Emacs version 21. It says to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17224 evaluate the following form and use the result as a string to display. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17225 In this case, the expression displays the first component of the full |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17226 system name. The end of the first component is a @samp{.} (`period'), |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17227 so I use the @code{string-match} function to tell me the length of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17228 first component. The substring from the zeroth character to that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17229 length is the name of the machine. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17230 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17231 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17232 This is the expression: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17233 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17234 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17235 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17236 (:eval (substring |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17237 (system-name) 0 (string-match "\\..+" (system-name)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17238 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17239 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17240 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17241 @samp{%[} and @samp{%]} cause a pair of square brackets |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17242 to appear for each recursive editing level. @samp{%n} says `Narrow' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17243 when narrowing is in effect. @samp{%P} tells you the percentage of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17244 the buffer that is above the bottom of the window, or `Top', `Bottom', |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17245 or `All'. (A lower case @samp{p} tell you the percentage above the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17246 @emph{top} of the window.) @samp{%-} inserts enough dashes to fill |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17247 out the line. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17248 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17249 Remember, ``You don't have to like Emacs to like it'' --- your own |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17250 Emacs can have different colors, different commands, and different |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17251 keys than a default Emacs. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17252 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17253 On the other hand, if you want to bring up a plain `out of the box' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17254 Emacs, with no customization, type: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17255 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17256 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17257 emacs -q |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17258 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17259 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17260 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17261 This will start an Emacs that does @emph{not} load your |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17262 @file{~/.emacs} initialization file. A plain, default Emacs. Nothing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17263 more. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17264 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17265 @node Debugging, Conclusion, Emacs Initialization, Top |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17266 @chapter Debugging |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17267 @cindex debugging |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17268 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17269 GNU Emacs has two debuggers, @code{debug} and @code{edebug}. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17270 first is built into the internals of Emacs and is always with you; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17271 the second requires that you instrument a function before you can use it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17272 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17273 Both debuggers are described extensively in @ref{Debugging, , |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17274 Debugging Lisp Programs, elisp, The GNU Emacs Lisp Reference Manual}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17275 In this chapter, I will walk through a short example of each. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17276 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17277 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17278 * debug:: How to use the built-in debugger. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17279 * debug-on-entry:: Start debugging when you call a function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17280 * debug-on-quit:: Start debugging when you quit with @kbd{C-g}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17281 * edebug:: How to use Edebug, a source level debugger. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17282 * Debugging Exercises:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17283 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17284 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17285 @node debug, debug-on-entry, Debugging, Debugging |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17286 @section @code{debug} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17287 @findex debug |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17288 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17289 Suppose you have written a function definition that is intended to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17290 return the sum of the numbers 1 through a given number. (This is the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17291 @code{triangle} function discussed earlier. @xref{Decrementing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17292 Example, , Example with Decrementing Counter}, for a discussion.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17293 @c xref{Decrementing Loop,, Loop with a Decrementing Counter}, for a discussion.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17294 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17295 However, your function definition has a bug. You have mistyped |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17296 @samp{1=} for @samp{1-}. Here is the broken definition: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17297 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17298 @findex triangle-bugged |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17299 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17300 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17301 (defun triangle-bugged (number) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17302 "Return sum of numbers 1 through NUMBER inclusive." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17303 (let ((total 0)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17304 (while (> number 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17305 (setq total (+ total number)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17306 (setq number (1= number))) ; @r{Error here.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17307 total)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17308 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17309 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17310 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17311 If you are reading this in Info, you can evaluate this definition in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17312 the normal fashion. You will see @code{triangle-bugged} appear in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17313 echo area. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17314 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17315 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17316 Now evaluate the @code{triangle-bugged} function with an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17317 argument of 4: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17318 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17319 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17320 (triangle-bugged 4) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17321 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17322 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17323 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17324 In GNU Emacs version 21, you will create and enter a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17325 @file{*Backtrace*} buffer that says: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17326 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17327 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17328 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17329 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17330 ---------- Buffer: *Backtrace* ---------- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17331 Debugger entered--Lisp error: (void-function 1=) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17332 (1= number) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17333 (setq number (1= number)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17334 (while (> number 0) (setq total (+ total number)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17335 (setq number (1= number))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17336 (let ((total 0)) (while (> number 0) (setq total ...) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17337 (setq number ...)) total) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17338 triangle-bugged(4) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17339 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17340 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17341 eval((triangle-bugged 4)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17342 eval-last-sexp-1(nil) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17343 eval-last-sexp(nil) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17344 call-interactively(eval-last-sexp) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17345 ---------- Buffer: *Backtrace* ---------- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17346 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17347 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17348 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17349 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17350 (I have reformatted this example slightly; the debugger does not fold |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17351 long lines. As usual, you can quit the debugger by typing @kbd{q} in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17352 the @file{*Backtrace*} buffer.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17353 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17354 In practice, for a bug as simple as this, the `Lisp error' line will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17355 tell you what you need to know to correct the definition. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17356 function @code{1=} is `void'. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17357 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17358 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17359 In GNU Emacs 20 and before, you will see: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17360 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17361 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17362 Symbol's function definition is void:@: 1= |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17363 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17364 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17365 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17366 which has the same meaning as the @file{*Backtrace*} buffer line in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17367 version 21. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17368 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17369 However, suppose you are not quite certain what is going on? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17370 You can read the complete backtrace. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17371 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17372 In this case, you need to run GNU Emacs 21, which automatically starts |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17373 the debugger that puts you in the @file{*Backtrace*} buffer; or else, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17374 you need to start the debugger manually as described below. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17375 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17376 Read the @file{*Backtrace*} buffer from the bottom up; it tells you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17377 what Emacs did that led to the error. Emacs made an interactive call |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17378 to @kbd{C-x C-e} (@code{eval-last-sexp}), which led to the evaluation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17379 of the @code{triangle-bugged} expression. Each line above tells you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17380 what the Lisp interpreter evaluated next. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17381 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17382 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17383 The third line from the top of the buffer is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17384 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17385 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17386 (setq number (1= number)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17387 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17388 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17389 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17390 Emacs tried to evaluate this expression; in order to do so, it tried |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17391 to evaluate the inner expression shown on the second line from the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17392 top: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17393 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17394 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17395 (1= number) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17396 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17397 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17398 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17399 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17400 This is where the error occurred; as the top line says: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17401 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17402 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17403 Debugger entered--Lisp error: (void-function 1=) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17404 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17405 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17406 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17407 You can correct the mistake, re-evaluate the function definition, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17408 then run your test again. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17409 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17410 @node debug-on-entry, debug-on-quit, debug, Debugging |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17411 @section @code{debug-on-entry} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17412 @findex debug-on-entry |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17413 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17414 GNU Emacs 21 starts the debugger automatically when your function has |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17415 an error. GNU Emacs version 20 and before did not; it simply |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17416 presented you with an error message. You had to start the debugger |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17417 manually. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17418 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17419 You can start the debugger manually for all versions of Emacs; the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17420 advantage is that the debugger runs even if you do not have a bug in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17421 your code. Sometimes your code will be free of bugs! |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17422 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17423 You can enter the debugger when you call the function by calling |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17424 @code{debug-on-entry}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17425 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17426 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17427 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17428 Type: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17429 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17430 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17431 M-x debug-on-entry RET triangle-bugged RET |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17432 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17433 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17434 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17435 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17436 Now, evaluate the following: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17437 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17438 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17439 (triangle-bugged 5) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17440 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17441 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17442 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17443 All versions of Emacs will create a @file{*Backtrace*} buffer and tell |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17444 you that it is beginning to evaluate the @code{triangle-bugged} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17445 function: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17446 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17447 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17448 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17449 ---------- Buffer: *Backtrace* ---------- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17450 Debugger entered--entering a function: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17451 * triangle-bugged(5) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17452 eval((triangle-bugged 5)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17453 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17454 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17455 eval-last-sexp-1(nil) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17456 eval-last-sexp(nil) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17457 call-interactively(eval-last-sexp) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17458 ---------- Buffer: *Backtrace* ---------- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17459 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17460 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17461 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17462 In the @file{*Backtrace*} buffer, type @kbd{d}. Emacs will evaluate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17463 the first expression in @code{triangle-bugged}; the buffer will look |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17464 like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17465 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17466 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17467 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17468 ---------- Buffer: *Backtrace* ---------- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17469 Debugger entered--beginning evaluation of function call form: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17470 * (let ((total 0)) (while (> number 0) (setq total ...) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17471 (setq number ...)) total) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17472 * triangle-bugged(5) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17473 eval((triangle-bugged 5)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17474 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17475 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17476 eval-last-sexp-1(nil) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17477 eval-last-sexp(nil) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17478 call-interactively(eval-last-sexp) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17479 ---------- Buffer: *Backtrace* ---------- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17480 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17481 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17482 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17483 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17484 Now, type @kbd{d} again, eight times, slowly. Each time you type |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17485 @kbd{d}, Emacs will evaluate another expression in the function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17486 definition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17487 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17488 @need 1750 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17489 Eventually, the buffer will look like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17490 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17491 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17492 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17493 ---------- Buffer: *Backtrace* ---------- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17494 Debugger entered--beginning evaluation of function call form: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17495 * (setq number (1= number)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17496 * (while (> number 0) (setq total (+ total number)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17497 (setq number (1= number))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17498 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17499 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17500 * (let ((total 0)) (while (> number 0) (setq total ...) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17501 (setq number ...)) total) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17502 * triangle-bugged(5) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17503 eval((triangle-bugged 5)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17504 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17505 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17506 eval-last-sexp-1(nil) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17507 eval-last-sexp(nil) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17508 call-interactively(eval-last-sexp) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17509 ---------- Buffer: *Backtrace* ---------- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17510 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17511 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17512 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17513 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17514 Finally, after you type @kbd{d} two more times, Emacs will reach the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17515 error, and the top two lines of the @file{*Backtrace*} buffer will look |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17516 like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17517 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17518 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17519 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17520 ---------- Buffer: *Backtrace* ---------- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17521 Debugger entered--Lisp error: (void-function 1=) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17522 * (1= number) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17523 @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17524 ---------- Buffer: *Backtrace* ---------- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17525 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17526 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17527 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17528 By typing @kbd{d}, you were able to step through the function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17529 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17530 You can quit a @file{*Backtrace*} buffer by typing @kbd{q} in it; this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17531 quits the trace, but does not cancel @code{debug-on-entry}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17532 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17533 @findex cancel-debug-on-entry |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17534 To cancel the effect of @code{debug-on-entry}, call |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17535 @code{cancel-debug-on-entry} and the name of the function, like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17536 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17537 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17538 M-x cancel-debug-on-entry RET triangle-bugged RET |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17539 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17540 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17541 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17542 (If you are reading this in Info, cancel @code{debug-on-entry} now.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17543 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17544 @node debug-on-quit, edebug, debug-on-entry, Debugging |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17545 @section @code{debug-on-quit} and @code{(debug)} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17546 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17547 In addition to setting @code{debug-on-error} or calling @code{debug-on-entry}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17548 there are two other ways to start @code{debug}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17549 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17550 @findex debug-on-quit |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17551 You can start @code{debug} whenever you type @kbd{C-g} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17552 (@code{keyboard-quit}) by setting the variable @code{debug-on-quit} to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17553 @code{t}. This is useful for debugging infinite loops. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17554 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17555 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17556 @cindex @code{(debug)} in code |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17557 Or, you can insert a line that says @code{(debug)} into your code |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17558 where you want the debugger to start, like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17559 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17560 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17561 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17562 (defun triangle-bugged (number) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17563 "Return sum of numbers 1 through NUMBER inclusive." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17564 (let ((total 0)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17565 (while (> number 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17566 (setq total (+ total number)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17567 (debug) ; @r{Start debugger.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17568 (setq number (1= number))) ; @r{Error here.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17569 total)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17570 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17571 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17572 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17573 The @code{debug} function is described in detail in @ref{Debugger, , |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17574 The Lisp Debugger, elisp, The GNU Emacs Lisp Reference Manual}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17575 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17576 @node edebug, Debugging Exercises, debug-on-quit, Debugging |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17577 @section The @code{edebug} Source Level Debugger |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17578 @cindex Source level debugger |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17579 @findex edebug |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17580 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17581 Edebug is a source level debugger. Edebug normally displays the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17582 source of the code you are debugging, with an arrow at the left that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17583 shows which line you are currently executing. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17584 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17585 You can walk through the execution of a function, line by line, or run |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17586 quickly until reaching a @dfn{breakpoint} where execution stops. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17587 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17588 Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17589 Lisp Reference Manual}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17590 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17591 Here is a bugged function definition for @code{triangle-recursively}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17592 @xref{Recursive triangle function, , Recursion in place of a counter}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17593 for a review of it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17594 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17595 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17596 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17597 (defun triangle-recursively-bugged (number) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17598 "Return sum of numbers 1 through NUMBER inclusive. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17599 Uses recursion." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17600 (if (= number 1) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17601 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17602 (+ number |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17603 (triangle-recursively-bugged |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17604 (1= number))))) ; @r{Error here.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17605 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17606 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17607 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17608 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17609 Normally, you would install this definition by positioning your cursor |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17610 after the function's closing parenthesis and typing @kbd{C-x C-e} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17611 (@code{eval-last-sexp}) or else by positioning your cursor within the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17612 definition and typing @kbd{C-M-x} (@code{eval-defun}). (By default, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17613 the @code{eval-defun} command works only in Emacs Lisp mode or in Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17614 Interactive mode.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17615 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17616 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17617 However, to prepare this function definition for Edebug, you must |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17618 first @dfn{instrument} the code using a different command. You can do |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17619 this by positioning your cursor within the definition and typing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17620 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17621 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17622 M-x edebug-defun RET |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17623 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17624 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17625 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17626 This will cause Emacs to load Edebug automatically if it is not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17627 already loaded, and properly instrument the function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17628 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17629 After instrumenting the function, place your cursor after the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17630 following expression and type @kbd{C-x C-e} (@code{eval-last-sexp}): |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17631 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17632 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17633 (triangle-recursively-bugged 3) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17634 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17635 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17636 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17637 You will be jumped back to the source for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17638 @code{triangle-recursively-bugged} and the cursor positioned at the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17639 beginning of the @code{if} line of the function. Also, you will see |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17640 an arrowhead at the left hand side of that line. The arrowhead marks |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17641 the line where the function is executing. (In the following examples, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17642 we show the arrowhead with @samp{=>}; in a windowing system, you may |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17643 see the arrowhead as a solid triangle in the window `fringe'.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17644 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17645 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17646 =>@point{}(if (= number 1) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17647 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17648 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17649 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17650 @iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17651 In the example, the location of point is displayed with a star, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17652 @samp{@point{}} (in Info, it is displayed as @samp{-!-}). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17653 @end iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17654 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17655 In the example, the location of point is displayed as @samp{@point{}} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17656 (in a printed book, it is displayed with a five pointed star). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17657 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17658 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17659 If you now press @key{SPC}, point will move to the next expression to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17660 be executed; the line will look like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17661 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17662 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17663 =>(if @point{}(= number 1) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17664 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17665 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17666 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17667 As you continue to press @key{SPC}, point will move from expression to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17668 expression. At the same time, whenever an expression returns a value, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17669 that value will be displayed in the echo area. For example, after you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17670 move point past @code{number}, you will see the following: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17671 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17672 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17673 Result: 3 = C-c |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17674 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17675 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17676 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17677 This means the value of @code{number} is 3, which is @sc{ascii} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17678 `control-c' (the third letter of the alphabet). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17679 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17680 You can continue moving through the code until you reach the line with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17681 the error. Before evaluation, that line looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17682 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17683 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17684 => @point{}(1= number))))) ; @r{Error here.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17685 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17686 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17687 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17688 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17689 When you press @key{SPC} once again, you will produce an error message |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17690 that says: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17691 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17692 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17693 Symbol's function definition is void:@: 1= |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17694 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17695 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17696 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17697 This is the bug. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17698 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17699 Press @kbd{q} to quit Edebug. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17700 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17701 To remove instrumentation from a function definition, simply |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17702 re-evaluate it with a command that does not instrument it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17703 For example, you could place your cursor after the definition's |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17704 closing parenthesis and type @kbd{C-x C-e}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17705 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17706 Edebug does a great deal more than walk with you through a function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17707 You can set it so it races through on its own, stopping only at an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17708 error or at specified stopping points; you can cause it to display the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17709 changing values of various expressions; you can find out how many |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17710 times a function is called, and more. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17711 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17712 Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17713 Lisp Reference Manual}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17714 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17715 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17716 @node Debugging Exercises, , edebug, Debugging |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17717 @section Debugging Exercises |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17718 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17719 @itemize @bullet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17720 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17721 Install the @code{count-words-region} function and then cause it to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17722 enter the built-in debugger when you call it. Run the command on a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17723 region containing two words. You will need to press @kbd{d} a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17724 remarkable number of times. On your system, is a `hook' called after |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17725 the command finishes? (For information on hooks, see @ref{Command |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17726 Overview, , Command Loop Overview, elisp, The GNU Emacs Lisp Reference |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17727 Manual}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17728 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17729 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17730 Copy @code{count-words-region} into the @file{*scratch*} buffer, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17731 instrument the function for Edebug, and walk through its execution. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17732 The function does not need to have a bug, although you can introduce |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17733 one if you wish. If the function lacks a bug, the walk-through |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17734 completes without problems. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17735 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17736 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17737 While running Edebug, type @kbd{?} to see a list of all the Edebug commands. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17738 (The @code{global-edebug-prefix} is usually @kbd{C-x X}, i.e.@: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17739 @kbd{@key{CTL}-x} followed by an upper case @kbd{X}; use this prefix |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17740 for commands made outside of the Edebug debugging buffer.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17741 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17742 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17743 In the Edebug debugging buffer, use the @kbd{p} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17744 (@code{edebug-bounce-point}) command to see where in the region the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17745 @code{count-words-region} is working. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17746 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17747 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17748 Move point to some spot further down function and then type the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17749 @kbd{h} (@code{edebug-goto-here}) command to jump to that location. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17750 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17751 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17752 Use the @kbd{t} (@code{edebug-trace-mode}) command to cause Edebug to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17753 walk through the function on its own; use an upper case @kbd{T} for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17754 @code{edebug-Trace-fast-mode}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17755 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17756 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17757 Set a breakpoint, then run Edebug in Trace mode until it reaches the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17758 stopping point. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17759 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17760 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17761 @node Conclusion, the-the, Debugging, Top |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17762 @chapter Conclusion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17763 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17764 We have now reached the end of this Introduction. You have now |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17765 learned enough about programming in Emacs Lisp to set values, to write |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17766 simple @file{.emacs} files for yourself and your friends, and write |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17767 simple customizations and extensions to Emacs. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17768 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17769 This is a place to stop. Or, if you wish, you can now go onward, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17770 teach yourself. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17771 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17772 You have learned some of the basic nuts and bolts of programming. But |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17773 only some. There are a great many more brackets and hinges that are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17774 easy to use that we have not touched. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17775 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17776 A path you can follow right now lies among the sources to GNU Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17777 and in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17778 @ifnotinfo |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17779 @cite{The GNU Emacs Lisp Reference Manual}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17780 @end ifnotinfo |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17781 @ifinfo |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17782 @ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17783 Emacs Lisp Reference Manual}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17784 @end ifinfo |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17785 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17786 The Emacs Lisp sources are an adventure. When you read the sources and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17787 come across a function or expression that is unfamiliar, you need to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17788 figure out or find out what it does. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17789 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17790 Go to the Reference Manual. It is a thorough, complete, and fairly |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17791 easy-to-read description of Emacs Lisp. It is written not only for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17792 experts, but for people who know what you know. (The @cite{Reference |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17793 Manual} comes with the standard GNU Emacs distribution. Like this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17794 introduction, it comes as a Texinfo source file, so you can read it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17795 on-line and as a typeset, printed book.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17796 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17797 Go to the other on-line help that is part of GNU Emacs: the on-line |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17798 documentation for all functions, and @code{find-tags}, the program |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17799 that takes you to sources. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17801 Here is an example of how I explore the sources. Because of its name, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17802 @file{simple.el} is the file I looked at first, a long time ago. As |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17803 it happens some of the functions in @file{simple.el} are complicated, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17804 or at least look complicated at first sight. The @code{open-line} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17805 function, for example, looks complicated. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17806 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17807 You may want to walk through this function slowly, as we did with the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17808 @code{forward-sentence} function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17809 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17810 (@xref{forward-sentence}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17811 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17812 @iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17813 (@xref{forward-sentence, , @code{forward-sentence}}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17814 @end iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17815 Or you may want to skip that function and look at another, such as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17816 @code{split-line}. You don't need to read all the functions. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17817 According to @code{count-words-in-defun}, the @code{split-line} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17818 function contains 27 words and symbols. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17819 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17820 Even though it is short, @code{split-line} contains four expressions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17821 we have not studied: @code{skip-chars-forward}, @code{indent-to}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17822 @code{current-column} and @samp{?\n}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17823 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17824 Consider the @code{skip-chars-forward} function. (It is part of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17825 function definition for @code{back-to-indentation}, which is shown in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17826 @ref{Review, , Review}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17827 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17828 In GNU Emacs, you can find out more about @code{skip-chars-forward} by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17829 typing @kbd{C-h f} (@code{describe-function}) and the name of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17830 function. This gives you the function documentation. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17831 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17832 You may be able to guess what is done by a well named function such as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17833 @code{indent-to}; or you can look it up, too. Incidentally, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17834 @code{describe-function} function itself is in @file{help.el}; it is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17835 one of those long, but decipherable functions. You can look up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17836 @code{describe-function} using the @kbd{C-h f} command! |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17837 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17838 In this instance, since the code is Lisp, the @file{*Help*} buffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17839 contains the name of the library containing the function's source. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17840 You can put point over the name of the library and press the RET key, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17841 which in this situation is bound to @code{help-follow}, and be taken |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17842 directly to the source, in the same way as @kbd{M-.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17843 (@code{find-tag}). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17844 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17845 The definition for @code{describe-function} illustrates how to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17846 customize the @code{interactive} expression without using the standard |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17847 character codes; and it shows how to create a temporary buffer. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17848 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17849 (The @code{indent-to} function is written in C rather than Emacs Lisp; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17850 it is a `built-in' function. @code{help-follow} only provides you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17851 with the documentation of a built-in function; it does not take you to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17852 the source. But @code{find-tag} will take you to the source, if |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17853 properly set up.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17854 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17855 You can look at a function's source using @code{find-tag}, which is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17856 bound to @kbd{M-.} Finally, you can find out what the Reference |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17857 Manual has to say by visiting the manual in Info, and typing @kbd{i} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17858 (@code{Info-index}) and the name of the function, or by looking up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17859 @code{skip-chars-forward} in the index to a printed copy of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17860 manual. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17861 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17862 Similarly, you can find out what is meant by @samp{?\n}. You can try |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17863 using @code{Info-index} with @samp{?\n}. It turns out that this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17864 action won't help; but don't give up. If you search the index for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17865 @samp{\n} without the @samp{?}, you will be taken directly to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17866 relevant section of the manual. (@xref{Character Type, , Character |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17867 Type, elisp, The GNU Emacs Lisp Reference Manual}. @samp{?\n} stands |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17868 for the newline character.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17869 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17870 Other interesting source files include @file{paragraphs.el}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17871 @file{loaddefs.el}, and @file{loadup.el}. The @file{paragraphs.el} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17872 file includes short, easily understood functions as well as longer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17873 ones. The @file{loaddefs.el} file contains the many standard |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17874 autoloads and many keymaps. I have never looked at it all; only at |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17875 parts. @file{loadup.el} is the file that loads the standard parts of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17876 Emacs; it tells you a great deal about how Emacs is built. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17877 (@xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17878 Reference Manual}, for more about building.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17879 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17880 As I said, you have learned some nuts and bolts; however, and very |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17881 importantly, we have hardly touched major aspects of programming; I |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17882 have said nothing about how to sort information, except to use the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17883 predefined @code{sort} function; I have said nothing about how to store |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17884 information, except to use variables and lists; I have said nothing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17885 about how to write programs that write programs. These are topics for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17886 another, and different kind of book, a different kind of learning. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17887 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17888 What you have done is learn enough for much practical work with GNU |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17889 Emacs. What you have done is get started. This is the end of a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17890 beginning. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17891 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17892 @c ================ Appendix ================ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17893 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17894 @node the-the, Kill Ring, Conclusion, Top |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17895 @appendix The @code{the-the} Function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17896 @findex the-the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17897 @cindex Duplicated words function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17898 @cindex Words, duplicated |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17899 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17900 Sometimes when you you write text, you duplicate words---as with ``you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17901 you'' near the beginning of this sentence. I find that most |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17902 frequently, I duplicate ``the'; hence, I call the function for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17903 detecting duplicated words, @code{the-the}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17904 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17905 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17906 As a first step, you could use the following regular expression to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17907 search for duplicates: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17908 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17909 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17910 \\(\\w+[ \t\n]+\\)\\1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17911 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17912 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17913 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17914 This regexp matches one or more word-constituent characters followed |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17915 by one or more spaces, tabs, or newlines. However, it does not detect |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17916 duplicated words on different lines, since the ending of the first |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17917 word, the end of the line, is different from the ending of the second |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17918 word, a space. (For more information about regular expressions, see |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17919 @ref{Regexp Search, , Regular Expression Searches}, as well as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17920 @ref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17921 Manual}, and @ref{Regular Expressions, , Regular Expressions, elisp, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17922 The GNU Emacs Lisp Reference Manual}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17923 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17924 You might try searching just for duplicated word-constituent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17925 characters but that does not work since the pattern detects doubles |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17926 such as the two occurrences of `th' in `with the'. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17927 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17928 Another possible regexp searches for word-constituent characters |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17929 followed by non-word-constituent characters, reduplicated. Here, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17930 @w{@samp{\\w+}} matches one or more word-constituent characters and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17931 @w{@samp{\\W*}} matches zero or more non-word-constituent characters. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17932 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17933 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17934 \\(\\(\\w+\\)\\W*\\)\\1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17935 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17936 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17937 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17938 Again, not useful. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17939 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17940 Here is the pattern that I use. It is not perfect, but good enough. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17941 @w{@samp{\\b}} matches the empty string, provided it is at the beginning |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17942 or end of a word; @w{@samp{[^@@ \n\t]+}} matches one or more occurrences of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17943 any characters that are @emph{not} an @@-sign, space, newline, or tab. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17944 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17945 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17946 \\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17947 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17948 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17949 One can write more complicated expressions, but I found that this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17950 expression is good enough, so I use it. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17951 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17952 Here is the @code{the-the} function, as I include it in my |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17953 @file{.emacs} file, along with a handy global key binding: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17954 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17955 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17956 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17957 (defun the-the () |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17958 "Search forward for for a duplicated word." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17959 (interactive) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17960 (message "Searching for for duplicated words ...") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17961 (push-mark) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17962 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17963 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17964 ;; This regexp is not perfect |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17965 ;; but is fairly good over all: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17966 (if (re-search-forward |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17967 "\\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b" nil 'move) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17968 (message "Found duplicated word.") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17969 (message "End of buffer"))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17970 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17971 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17972 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17973 ;; Bind `the-the' to C-c \ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17974 (global-set-key "\C-c\\" 'the-the) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17975 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17976 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17977 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17978 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17979 Here is test text: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17980 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17981 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17982 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17983 one two two three four five |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17984 five six seven |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17985 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17986 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17987 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17988 You can substitute the other regular expressions shown above in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17989 function definition and try each of them on this list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17990 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17991 @node Kill Ring, Full Graph, the-the, Top |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17992 @appendix Handling the Kill Ring |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17993 @cindex Kill ring handling |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17994 @cindex Handling the kill ring |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17995 @cindex Ring, making a list like a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17996 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17997 The kill ring is a list that is transformed into a ring by the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17998 workings of the @code{rotate-yank-pointer} function. The @code{yank} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
17999 and @code{yank-pop} commands use the @code{rotate-yank-pointer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18000 function. This appendix describes the @code{rotate-yank-pointer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18001 function as well as both the @code{yank} and the @code{yank-pop} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18002 commands. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18003 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18004 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18005 * rotate-yank-pointer:: Move a pointer along a list and around. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18006 * yank:: Paste a copy of a clipped element. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18007 * yank-pop:: Insert first element pointed to. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18008 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18009 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18010 @node rotate-yank-pointer, yank, Kill Ring, Kill Ring |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18011 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18012 @appendixsec The @code{rotate-yank-pointer} Function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18013 @findex rotate-yank-pointer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18014 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18015 The @code{rotate-yank-pointer} function changes the element in the kill |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18016 ring to which @code{kill-ring-yank-pointer} points. For example, it can |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18017 change @code{kill-ring-yank-pointer} from pointing to the second |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18018 element to point to the third element. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18019 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18020 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18021 Here is the code for @code{rotate-yank-pointer}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18022 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18023 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18024 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18025 (defun rotate-yank-pointer (arg) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18026 "Rotate the yanking point in the kill ring." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18027 (interactive "p") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18028 (let ((length (length kill-ring))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18029 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18030 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18031 (if (zerop length) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18032 ;; @r{then-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18033 (error "Kill ring is empty") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18034 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18035 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18036 ;; @r{else-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18037 (setq kill-ring-yank-pointer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18038 (nthcdr (% (+ arg |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18039 (- length |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18040 (length |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18041 kill-ring-yank-pointer))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18042 length) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18043 kill-ring))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18044 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18045 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18046 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18047 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18048 * Understanding rotate-yk-ptr:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18049 * rotate-yk-ptr body:: The body of @code{rotate-yank-pointer}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18050 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18051 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18052 @node Understanding rotate-yk-ptr, rotate-yk-ptr body, rotate-yank-pointer, rotate-yank-pointer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18053 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18054 @unnumberedsubsec @code{rotate-yank-pointer} in Outline |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18055 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18056 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18057 The @code{rotate-yank-pointer} function looks complex, but as usual, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18058 it can be understood by taking it apart piece by piece. First look at |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18059 it in skeletal form: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18060 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18061 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18062 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18063 (defun rotate-yank-pointer (arg) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18064 "Rotate the yanking point in the kill ring." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18065 (interactive "p") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18066 (let @var{varlist} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18067 @var{body}@dots{}) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18068 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18069 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18070 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18071 This function takes one argument, called @code{arg}. It has a brief |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18072 documentation string; and it is interactive with a small @samp{p}, which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18073 means that the argument must be a processed prefix passed to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18074 function as a number. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18075 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18076 The body of the function definition is a @code{let} expression, which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18077 itself has a body as well as a @var{varlist}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18078 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18079 The @code{let} expression declares a variable that will be only usable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18080 within the bounds of this function. This variable is called |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18081 @code{length} and is bound to a value that is equal to the number of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18082 items in the kill ring. This is done by using the function called |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18083 @code{length}. (Note that this function has the same name as the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18084 variable called @code{length}; but one use of the word is to name the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18085 function and the other is to name the variable. The two are quite |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18086 distinct. Similarly, an English speaker will distinguish between the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18087 meanings of the word @samp{ship} when he says: "I must ship this package |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18088 immediately." and "I must get aboard the ship immediately.") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18089 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18090 The function @code{length} tells the number of items there are in a list, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18091 so @code{(length kill-ring)} returns the number of items there are in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18092 kill ring. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18093 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18094 @node rotate-yk-ptr body, , Understanding rotate-yk-ptr, rotate-yank-pointer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18095 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18096 @appendixsubsec The Body of @code{rotate-yank-pointer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18097 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18098 The body of @code{rotate-yank-pointer} is a @code{let} expression and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18099 the body of the @code{let} expression is an @code{if} expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18100 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18101 The purpose of the @code{if} expression is to find out whether there is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18102 anything in the kill ring. If the kill ring is empty, the @code{error} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18103 function stops evaluation of the function and prints a message in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18104 echo area. On the other hand, if the kill ring has something in it, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18105 work of the function is done. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18106 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18107 Here is the if-part and then-part of the @code{if} expression: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18108 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18109 @findex zerop |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18110 @findex error |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18111 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18112 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18113 (if (zerop length) ; @r{if-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18114 (error "Kill ring is empty") ; @r{then-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18115 @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18116 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18117 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18118 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18119 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18120 If there is not anything in the kill ring, its length must be zero and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18121 an error message sent to the user: @samp{Kill ring is empty}. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18122 @code{if} expression uses the function @code{zerop} which returns true |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18123 if the value it is testing is zero. When @code{zerop} tests true, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18124 then-part of the @code{if} is evaluated. The then-part is a list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18125 starting with the function @code{error}, which is a function that is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18126 similar to the @code{message} function (@pxref{message}), in that it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18127 prints a one-line message in the echo area. However, in addition to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18128 printing a message, @code{error} also stops evaluation of the function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18129 within which it is embedded. This means that the rest of the function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18130 will not be evaluated if the length of the kill ring is zero. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18131 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18132 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18133 * Digression concerning error:: How to mislead humans, but not computers. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18134 * rotate-yk-ptr else-part:: The else-part of the @code{if} expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18135 * Remainder Function:: The remainder, @code{%}, function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18136 * rotate-yk-ptr remainder:: Using @code{%} in @code{rotate-yank-pointer}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18137 * kill-rng-yk-ptr last elt:: Pointing to the last element. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18138 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18139 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18140 @node Digression concerning error, rotate-yk-ptr else-part, rotate-yk-ptr body, rotate-yk-ptr body |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18141 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18142 @unnumberedsubsubsec Digression about the word `error' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18143 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18144 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18145 (In my opinion, it is slightly misleading, at least to humans, to use |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18146 the term `error' as the name of the @code{error} function. A better |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18147 term would be `cancel'. Strictly speaking, of course, you cannot |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18148 point to, much less rotate a pointer to a list that has no length, so |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18149 from the point of view of the computer, the word `error' is correct. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18150 But a human expects to attempt this sort of thing, if only to find out |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18151 whether the kill ring is full or empty. This is an act of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18152 exploration. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18153 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18154 (From the human point of view, the act of exploration and discovery is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18155 not necessarily an error, and therefore should not be labelled as one, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18156 even in the bowels of a computer. As it is, the code in Emacs implies |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18157 that a human who is acting virtuously, by exploring his or her |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18158 environment, is making an error. This is bad. Even though the computer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18159 takes the same steps as it does when there is an `error', a term such as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18160 `cancel' would have a clearer connotation.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18161 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18162 @node rotate-yk-ptr else-part, Remainder Function, Digression concerning error, rotate-yk-ptr body |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18163 @unnumberedsubsubsec The else-part of the @code{if} expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18164 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18165 The else-part of the @code{if} expression is dedicated to setting the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18166 value of @code{kill-ring-yank-pointer} when the kill ring has something |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18167 in it. The code looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18168 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18169 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18170 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18171 (setq kill-ring-yank-pointer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18172 (nthcdr (% (+ arg |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18173 (- length |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18174 (length kill-ring-yank-pointer))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18175 length) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18176 kill-ring))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18177 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18178 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18179 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18180 This needs some examination. Clearly, @code{kill-ring-yank-pointer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18181 is being set to be equal to some @sc{cdr} of the kill ring, using the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18182 @code{nthcdr} function that is described in an earlier section. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18183 (@xref{copy-region-as-kill}.) But exactly how does it do this? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18184 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18185 Before looking at the details of the code let's first consider the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18186 purpose of the @code{rotate-yank-pointer} function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18187 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18188 The @code{rotate-yank-pointer} function changes what |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18189 @code{kill-ring-yank-pointer} points to. If |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18190 @code{kill-ring-yank-pointer} starts by pointing to the first element |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18191 of a list, a call to @code{rotate-yank-pointer} causes it to point to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18192 the second element; and if @code{kill-ring-yank-pointer} points to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18193 second element, a call to @code{rotate-yank-pointer} causes it to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18194 point to the third element. (And if @code{rotate-yank-pointer} is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18195 given an argument greater than 1, it jumps the pointer that many |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18196 elements.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18197 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18198 The @code{rotate-yank-pointer} function uses @code{setq} to reset what |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18199 the @code{kill-ring-yank-pointer} points to. If |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18200 @code{kill-ring-yank-pointer} points to the first element of the kill |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18201 ring, then, in the simplest case, the @code{rotate-yank-pointer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18202 function must cause it to point to the second element. Put another |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18203 way, @code{kill-ring-yank-pointer} must be reset to have a value equal |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18204 to the @sc{cdr} of the kill ring. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18205 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18206 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18207 That is, under these circumstances, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18208 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18209 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18210 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18211 (setq kill-ring-yank-pointer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18212 ("some text" "a different piece of text" "yet more text")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18213 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18214 (setq kill-ring |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18215 ("some text" "a different piece of text" "yet more text")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18216 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18217 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18218 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18219 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18220 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18221 the code should do this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18222 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18223 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18224 (setq kill-ring-yank-pointer (cdr kill-ring)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18225 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18226 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18227 @need 1000 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18228 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18229 As a result, the @code{kill-ring-yank-pointer} will look like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18230 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18231 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18232 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18233 kill-ring-yank-pointer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18234 @result{} ("a different piece of text" "yet more text")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18235 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18236 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18237 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18238 The actual @code{setq} expression uses the @code{nthcdr} function to do |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18239 the job. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18240 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18241 As we have seen before (@pxref{nthcdr}), the @code{nthcdr} function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18242 works by repeatedly taking the @sc{cdr} of a list---it takes the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18243 @sc{cdr} of the @sc{cdr} of the @sc{cdr} @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18244 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18245 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18246 The two following expressions produce the same result: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18247 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18248 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18249 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18250 (setq kill-ring-yank-pointer (cdr kill-ring)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18251 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18252 (setq kill-ring-yank-pointer (nthcdr 1 kill-ring)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18253 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18254 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18255 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18256 In the @code{rotate-yank-pointer} function, however, the first |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18257 argument to @code{nthcdr} is a rather complex looking expression with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18258 lots of arithmetic inside of it: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18259 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18260 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18261 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18262 (% (+ arg |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18263 (- length |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18264 (length kill-ring-yank-pointer))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18265 length) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18266 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18267 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18268 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18269 As usual, we need to look at the most deeply embedded expression first |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18270 and then work our way towards the light. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18271 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18272 The most deeply embedded expression is @code{(length |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18273 kill-ring-yank-pointer)}. This finds the length of the current value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18274 the @code{kill-ring-yank-pointer}. (Remember that the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18275 @code{kill-ring-yank-pointer} is the name of a variable whose value is a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18276 list.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18277 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18278 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18279 The measurement of the length is inside the expression: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18280 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18281 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18282 (- length (length kill-ring-yank-pointer)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18283 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18284 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18285 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18286 In this expression, the first @code{length} is the variable that was |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18287 assigned the length of the kill ring in the @code{let} statement at the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18288 beginning of the function. (One might think this function would be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18289 clearer if the variable @code{length} were named |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18290 @code{length-of-kill-ring} instead; but if you look at the text of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18291 whole function, you will see that it is so short that naming this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18292 variable @code{length} is not a bother, unless you are pulling the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18293 function apart into very tiny pieces as we are doing here.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18294 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18295 So the line @code{(- length (length kill-ring-yank-pointer))} tells the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18296 difference between the length of the kill ring and the length of the list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18297 whose name is @code{kill-ring-yank-pointer}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18298 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18299 To see how all this fits into the @code{rotate-yank-pointer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18300 function, let's begin by analyzing the case where |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18301 @code{kill-ring-yank-pointer} points to the first element of the kill |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18302 ring, just as @code{kill-ring} does, and see what happens when |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18303 @code{rotate-yank-pointer} is called with an argument of 1. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18304 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18305 The variable @code{length} and the value of the expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18306 @code{(length kill-ring-yank-pointer)} will be the same since the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18307 variable @code{length} is the length of the kill ring and the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18308 @code{kill-ring-yank-pointer} is pointing to the whole kill ring. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18309 Consequently, the value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18310 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18311 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18312 (- length (length kill-ring-yank-pointer)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18313 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18314 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18315 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18316 will be zero. Since the value of @code{arg} will be 1, this will mean |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18317 that the value of the whole expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18318 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18319 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18320 (+ arg (- length (length kill-ring-yank-pointer))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18321 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18322 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18323 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18324 will be 1. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18325 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18326 Consequently, the argument to @code{nthcdr} will be found as the result of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18327 the expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18328 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18329 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18330 (% 1 length) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18331 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18332 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18333 @node Remainder Function, rotate-yk-ptr remainder, rotate-yk-ptr else-part, rotate-yk-ptr body |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18334 @unnumberedsubsubsec The @code{%} remainder function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18335 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18336 To understand @code{(% 1 length)}, we need to understand @code{%}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18337 According to its documentation (which I just found by typing @kbd{C-h |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18338 f @kbd{%} @key{RET}}), the @code{%} function returns the remainder of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18339 its first argument divided by its second argument. For example, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18340 remainder of 5 divided by 2 is 1. (2 goes into 5 twice with a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18341 remainder of 1.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18342 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18343 What surprises people who don't often do arithmetic is that a smaller |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18344 number can be divided by a larger number and have a remainder. In the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18345 example we just used, 5 was divided by 2. We can reverse that and ask, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18346 what is the result of dividing 2 by 5? If you can use fractions, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18347 answer is obviously 2/5 or .4; but if, as here, you can only use whole |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18348 numbers, the result has to be something different. Clearly, 5 can go into |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18349 2 zero times, but what of the remainder? To see what the answer is, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18350 consider a case that has to be familiar from childhood: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18351 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18352 @itemize @bullet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18353 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18354 5 divided by 5 is 1 with a remainder of 0; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18355 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18356 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18357 6 divided by 5 is 1 with a remainder of 1; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18358 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18359 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18360 7 divided by 5 is 1 with a remainder of 2. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18361 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18362 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18363 Similarly, 10 divided by 5 is 2 with a remainder of 0; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18364 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18365 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18366 11 divided by 5 is 2 with a remainder of 1; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18367 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18368 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18369 12 divided by 5 is 1 with a remainder of 2. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18370 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18371 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18372 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18373 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18374 By considering the cases as parallel, we can see that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18375 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18376 @itemize @bullet |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18377 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18378 zero divided by 5 must be zero with a remainder of zero; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18379 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18380 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18381 1 divided by 5 must be zero with a remainder of 1; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18382 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18383 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18384 2 divided by 5 must be zero with a remainder of 2; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18385 @end itemize |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18386 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18387 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18388 and so on. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18389 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18390 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18391 So, in this code, if the value of @code{length} is 5, then the result of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18392 evaluating |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18393 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18394 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18395 (% 1 5) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18396 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18397 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18398 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18399 is 1. (I just checked this by placing the cursor after the expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18400 and typing @kbd{C-x C-e}. Indeed, 1 is printed in the echo area.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18401 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18402 @node rotate-yk-ptr remainder, kill-rng-yk-ptr last elt, Remainder Function, rotate-yk-ptr body |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18403 @unnumberedsubsubsec Using @code{%} in @code{rotate-yank-pointer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18404 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18405 When the @code{kill-ring-yank-pointer} points to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18406 beginning of the kill ring, and the argument passed to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18407 @code{rotate-yank-pointer} is 1, the @code{%} expression returns 1: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18408 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18409 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18410 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18411 (- length (length kill-ring-yank-pointer)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18412 @result{} 0 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18413 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18414 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18415 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18416 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18417 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18418 therefore, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18419 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18420 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18421 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18422 (+ arg (- length (length kill-ring-yank-pointer))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18423 @result{} 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18424 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18425 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18426 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18427 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18428 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18429 and consequently: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18430 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18431 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18432 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18433 (% (+ arg (- length (length kill-ring-yank-pointer))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18434 length) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18435 @result{} 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18436 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18437 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18438 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18439 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18440 regardless of the value of @code{length}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18441 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18442 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18443 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18444 As a result of this, the @code{setq kill-ring-yank-pointer} expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18445 simplifies to: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18446 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18447 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18448 (setq kill-ring-yank-pointer (nthcdr 1 kill-ring)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18449 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18450 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18451 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18452 What it does is now easy to understand. Instead of pointing as it did |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18453 to the first element of the kill ring, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18454 @code{kill-ring-yank-pointer} is set to point to the second element. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18455 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18456 Clearly, if the argument passed to @code{rotate-yank-pointer} is two, then |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18457 the @code{kill-ring-yank-pointer} is set to @code{(nthcdr 2 kill-ring)}; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18458 and so on for different values of the argument. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18459 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18460 Similarly, if the @code{kill-ring-yank-pointer} starts out pointing to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18461 the second element of the kill ring, its length is shorter than the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18462 length of the kill ring by 1, so the computation of the remainder is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18463 based on the expression @code{(% (+ arg 1) length)}. This means that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18464 the @code{kill-ring-yank-pointer} is moved from the second element of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18465 the kill ring to the third element if the argument passed to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18466 @code{rotate-yank-pointer} is 1. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18467 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18468 @node kill-rng-yk-ptr last elt, , rotate-yk-ptr remainder, rotate-yk-ptr body |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18469 @unnumberedsubsubsec Pointing to the last element |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18470 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18471 The final question is, what happens if the @code{kill-ring-yank-pointer} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18472 is set to the @emph{last} element of the kill ring? Will a call to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18473 @code{rotate-yank-pointer} mean that nothing more can be taken from the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18474 kill ring? The answer is no. What happens is different and useful. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18475 The @code{kill-ring-yank-pointer} is set to point to the beginning of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18476 the kill ring instead. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18477 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18478 Let's see how this works by looking at the code, assuming the length of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18479 kill ring is 5 and the argument passed to @code{rotate-yank-pointer} is 1. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18480 When the @code{kill-ring-yank-pointer} points to the last element of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18481 the kill ring, its length is 1. The code looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18482 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18483 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18484 (% (+ arg (- length (length kill-ring-yank-pointer))) length) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18485 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18486 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18487 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18488 When the variables are replaced by their numeric values, the expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18489 looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18490 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18491 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18492 (% (+ 1 (- 5 1)) 5) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18493 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18494 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18495 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18496 This expression can be evaluated by looking at the most embedded inner |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18497 expression first and working outwards: The value of @code{(- 5 1)} is 4; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18498 the sum of @code{(+ 1 4)} is 5; and the remainder of dividing 5 by 5 is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18499 zero. So what @code{rotate-yank-pointer} will do is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18501 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18502 (setq kill-ring-yank-pointer (nthcdr 0 kill-ring)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18503 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18504 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18505 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18506 which will set the @code{kill-ring-yank-pointer} to point to the beginning |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18507 of the kill ring. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18508 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18509 So what happens with successive calls to @code{rotate-yank-pointer} is that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18510 it moves the @code{kill-ring-yank-pointer} from element to element in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18511 kill ring until it reaches the end; then it jumps back to the beginning. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18512 And this is why the kill ring is called a ring, since by jumping back to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18513 the beginning, it is as if the list has no end! (And what is a ring, but |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18514 an entity with no end?) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18515 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18516 @node yank, yank-pop, rotate-yank-pointer, Kill Ring |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18517 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18518 @appendixsec @code{yank} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18519 @findex yank |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18520 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18521 After learning about @code{rotate-yank-pointer}, the code for the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18522 @code{yank} function is almost easy. It has only one tricky part, which is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18523 the computation of the argument to be passed to @code{rotate-yank-pointer}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18524 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18525 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18526 The code looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18527 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18528 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18529 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18530 (defun yank (&optional arg) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18531 "Reinsert the last stretch of killed text. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18532 More precisely, reinsert the stretch of killed text most |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18533 recently killed OR yanked. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18534 With just C-U as argument, same but put point in front |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18535 (and mark at end). With argument n, reinsert the nth |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18536 most recently killed stretch of killed text. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18537 See also the command \\[yank-pop]." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18538 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18539 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18540 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18541 (interactive "*P") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18542 (rotate-yank-pointer (if (listp arg) 0 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18543 (if (eq arg '-) -1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18544 (1- arg)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18545 (push-mark (point)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18546 (insert (car kill-ring-yank-pointer)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18547 (if (consp arg) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18548 (exchange-point-and-mark))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18549 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18550 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18551 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18552 Glancing over this code, we can understand the last few lines readily |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18553 enough. The mark is pushed, that is, remembered; then the first element |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18554 (the @sc{car}) of what the @code{kill-ring-yank-pointer} points to is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18555 inserted; and then, if the argument passed the function is a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18556 @code{cons}, point and mark are exchanged so the point is put in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18557 front of the inserted text rather than at the end. This option is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18558 explained in the documentation. The function itself is interactive with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18559 @code{"*P"}. This means it will not work on a read-only buffer, and that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18560 the unprocessed prefix argument is passed to the function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18561 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18562 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18563 * rotate-yk-ptr arg:: Pass the argument to @code{rotate-yank-pointer}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18564 * rotate-yk-ptr negative arg:: Pass a negative argument. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18565 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18566 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18567 @node rotate-yk-ptr arg, rotate-yk-ptr negative arg, yank, yank |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18568 @unnumberedsubsubsec Passing the argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18569 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18570 The hard part of @code{yank} is understanding the computation that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18571 determines the value of the argument passed to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18572 @code{rotate-yank-pointer}. Fortunately, it is not so difficult as it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18573 looks at first sight. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18574 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18575 What happens is that the result of evaluating one or both of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18576 @code{if} expressions will be a number and that number will be the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18577 argument passed to @code{rotate-yank-pointer}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18578 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18579 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18580 Laid out with comments, the code looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18581 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18582 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18583 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18584 (if (listp arg) ; @r{if-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18585 0 ; @r{then-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18586 (if (eq arg '-) ; @r{else-part, inner if} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18587 -1 ; @r{inner if's then-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18588 (1- arg)))) ; @r{inner if's else-part} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18589 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18590 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18591 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18592 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18593 This code consists of two @code{if} expression, one the else-part of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18594 the other. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18595 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18596 The first or outer @code{if} expression tests whether the argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18597 passed to @code{yank} is a list. Oddly enough, this will be true if |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18598 @code{yank} is called without an argument---because then it will be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18599 passed the value of @code{nil} for the optional argument and an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18600 evaluation of @code{(listp nil)} returns true! So, if no argument is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18601 passed to @code{yank}, the argument passed to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18602 @code{rotate-yank-pointer} inside of @code{yank} is zero. This means |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18603 the pointer is not moved and the first element to which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18604 @code{kill-ring-yank-pointer} points is inserted, as we expect. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18605 Similarly, if the argument for @code{yank} is @kbd{C-u}, this will be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18606 read as a list, so again, a zero will be passed to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18607 @code{rotate-yank-pointer}. (@kbd{C-u} produces an unprocessed prefix |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18608 argument of @code{(4)}, which is a list of one element.) At the same |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18609 time, later in the function, this argument will be read as a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18610 @code{cons} so point will be put in the front and mark at the end of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18611 the insertion. (The @code{P} argument to @code{interactive} is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18612 designed to provide these values for the case when an optional |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18613 argument is not provided or when it is @kbd{C-u}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18614 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18615 The then-part of the outer @code{if} expression handles the case when |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18616 there is no argument or when it is @kbd{C-u}. The else-part handles the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18617 other situations. The else-part is itself another @code{if} expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18618 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18619 The inner @code{if} expression tests whether the argument is a minus |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18620 sign. (This is done by pressing the @key{META} and @kbd{-} keys at the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18621 same time, or the @key{ESC} key and then the @kbd{-} key). In this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18622 case, the @code{rotate-yank-pointer} function is passed @kbd{-1} as an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18623 argument. This moves the @code{kill-ring-yank-pointer} backwards, which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18624 is what is desired. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18625 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18626 If the true-or-false-test of the inner @code{if} expression is false |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18627 (that is, if the argument is not a minus sign), the else-part of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18628 expression is evaluated. This is the expression @code{(1- arg)}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18629 Because of the two @code{if} expressions, it will only occur when the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18630 argument is a positive number or when it is a negative number (not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18631 just a minus sign on its own). What @code{(1- arg)} does is decrement |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18632 the number and return it. (The @code{1-} function subtracts one from |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18633 its argument.) This means that if the argument to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18634 @code{rotate-yank-pointer} is 1, it is reduced to zero, which means |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18635 the first element to which @code{kill-ring-yank-pointer} points is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18636 yanked back, as you would expect. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18637 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18638 @node rotate-yk-ptr negative arg, , rotate-yk-ptr arg, yank |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18639 @unnumberedsubsubsec Passing a negative argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18640 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18641 Finally, the question arises, what happens if either the remainder |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18642 function, @code{%}, or the @code{nthcdr} function is passed a negative |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18643 argument, as they quite well may? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18644 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18645 The answers can be found by a quick test. When @code{(% -1 5)} is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18646 evaluated, a negative number is returned; and if @code{nthcdr} is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18647 called with a negative number, it returns the same value as if it were |
44899
ebddb2618c17
Fixed typographic errors.
Robert J. Chassell <bob@rattlesnake.com>
parents:
43431
diff
changeset
|
18648 called with a first argument of zero. This can be seen by evaluating |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18649 the following code. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18650 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18651 Here the @samp{@result{}} points to the result of evaluating the code |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18652 preceding it. This was done by positioning the cursor after the code |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18653 and typing @kbd{C-x C-e} (@code{eval-last-sexp}) in the usual fashion. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18654 You can do this if you are reading this in Info inside of GNU Emacs. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18655 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18656 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18657 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18658 (% -1 5) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18659 @result{} -1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18660 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18661 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18662 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18663 (setq animals '(cats dogs elephants)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18664 @result{} (cats dogs elephants) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18665 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18666 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18667 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18668 (nthcdr 1 animals) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18669 @result{} (dogs elephants) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18670 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18671 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18672 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18673 (nthcdr 0 animals) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18674 @result{} (cats dogs elephants) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18675 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18676 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18677 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18678 (nthcdr -1 animals) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18679 @result{} (cats dogs elephants) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18680 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18681 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18682 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18683 So, if a minus sign or a negative number is passed to @code{yank}, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18684 @code{kill-ring-yank-point} is rotated backwards until it reaches the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18685 beginning of the list. Then it stays there. Unlike the other case, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18686 when it jumps from the end of the list to the beginning of the list, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18687 making a ring, it stops. This makes sense. You often want to get back |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18688 to the most recently clipped out piece of text, but you don't usually |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18689 want to insert text from as many as thirty kill commands ago. So you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18690 need to work through the ring to get to the end, but won't cycle around |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18691 it inadvertently if you are trying to come back to the beginning. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18692 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18693 Incidentally, any number passed to @code{yank} with a minus sign |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18694 preceding it will be treated as @minus{}1. This is evidently a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18695 simplification for writing the program. You don't need to jump back |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18696 towards the beginning of the kill ring more than one place at a time |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18697 and doing this is easier than writing a function to determine the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18698 magnitude of the number that follows the minus sign. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18699 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18700 @node yank-pop, , yank, Kill Ring |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18701 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18702 @appendixsec @code{yank-pop} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18703 @findex yank-pop |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18704 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18705 After understanding @code{yank}, the @code{yank-pop} function is easy. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18706 Leaving out the documentation to save space, it looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18707 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18708 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18709 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18710 (defun yank-pop (arg) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18711 (interactive "*p") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18712 (if (not (eq last-command 'yank)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18713 (error "Previous command was not a yank")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18714 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18715 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18716 (setq this-command 'yank) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18717 (let ((before (< (point) (mark)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18718 (delete-region (point) (mark)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18719 (rotate-yank-pointer arg) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18720 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18721 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18722 (set-mark (point)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18723 (insert (car kill-ring-yank-pointer)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18724 (if before (exchange-point-and-mark)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18725 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18726 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18727 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18728 The function is interactive with a small @samp{p} so the prefix |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18729 argument is processed and passed to the function. The command can |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18730 only be used after a previous yank; otherwise an error message is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18731 sent. This check uses the variable @code{last-command} which is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18732 discussed elsewhere. (@xref{copy-region-as-kill}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18733 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18734 The @code{let} clause sets the variable @code{before} to true or false |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18735 depending whether point is before or after mark and then the region |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18736 between point and mark is deleted. This is the region that was just |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18737 inserted by the previous yank and it is this text that will be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18738 replaced. Next the @code{kill-ring-yank-pointer} is rotated so that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18739 the previously inserted text is not reinserted yet again. Mark is set |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18740 at the beginning of the place the new text will be inserted and then |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18741 the first element to which @code{kill-ring-yank-pointer} points is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18742 inserted. This leaves point after the new text. If in the previous |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18743 yank, point was left before the inserted text, point and mark are now |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18744 exchanged so point is again left in front of the newly inserted text. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18745 That is all there is to it! |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18746 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18747 @node Full Graph, GNU Free Documentation License, Kill Ring, Top |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18748 @appendix A Graph with Labelled Axes |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18749 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18750 Printed axes help you understand a graph. They convey scale. In an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18751 earlier chapter (@pxref{Readying a Graph, , Readying a Graph}), we |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18752 wrote the code to print the body of a graph. Here we write the code |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18753 for printing and labelling vertical and horizontal axes, along with the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18754 body itself. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18755 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18756 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18757 * Labelled Example:: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18758 * print-graph Varlist:: @code{let} expression in @code{print-graph}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18759 * print-Y-axis:: Print a label for the vertical axis. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18760 * print-X-axis:: Print a horizontal label. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18761 * Print Whole Graph:: The function to print a complete graph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18762 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18763 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18764 @node Labelled Example, print-graph Varlist, Full Graph, Full Graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18765 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18766 @unnumberedsec Labelled Example Graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18767 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18768 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18769 Since insertions fill a buffer to the right and below point, the new |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18770 graph printing function should first print the Y or vertical axis, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18771 then the body of the graph, and finally the X or horizontal axis. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18772 This sequence lays out for us the contents of the function: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18773 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18774 @enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18775 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18776 Set up code. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18777 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18778 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18779 Print Y axis. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18780 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18781 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18782 Print body of graph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18783 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18784 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18785 Print X axis. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18786 @end enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18787 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18788 @need 800 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18789 Here is an example of how a finished graph should look: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18790 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18791 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18792 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18793 10 - |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18794 * |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18795 * * |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18796 * ** |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18797 * *** |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18798 5 - * ******* |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18799 * *** ******* |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18800 ************* |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18801 *************** |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18802 1 - **************** |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18803 | | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18804 1 5 10 15 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18805 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18806 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18807 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18808 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18809 In this graph, both the vertical and the horizontal axes are labelled |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18810 with numbers. However, in some graphs, the horizontal axis is time |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18811 and would be better labelled with months, like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18812 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18813 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18814 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18815 5 - * |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18816 * ** * |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18817 ******* |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18818 ********** ** |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18819 1 - ************** |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18820 | ^ | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18821 Jan June Jan |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18822 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18823 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18824 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18825 Indeed, with a little thought, we can easily come up with a variety of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18826 vertical and horizontal labelling schemes. Our task could become |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18827 complicated. But complications breed confusion. Rather than permit |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18828 this, it is better choose a simple labelling scheme for our first |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18829 effort, and to modify or replace it later. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18830 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18831 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18832 These considerations suggest the following outline for the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18833 @code{print-graph} function: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18834 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18835 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18836 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18837 (defun print-graph (numbers-list) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18838 "@var{documentation}@dots{}" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18839 (let ((height @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18840 @dots{})) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18841 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18842 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18843 (print-Y-axis height @dots{} ) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18844 (graph-body-print numbers-list) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18845 (print-X-axis @dots{} ))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18846 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18847 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18848 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18849 We can work on each part of the @code{print-graph} function definition |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18850 in turn. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18851 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18852 @node print-graph Varlist, print-Y-axis, Labelled Example, Full Graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18853 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18854 @appendixsec The @code{print-graph} Varlist |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18855 @cindex @code{print-graph} varlist |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18856 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18857 In writing the @code{print-graph} function, the first task is to write |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18858 the varlist in the @code{let} expression. (We will leave aside for the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18859 moment any thoughts about making the function interactive or about the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18860 contents of its documentation string.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18861 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18862 The varlist should set several values. Clearly, the top of the label |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18863 for the vertical axis must be at least the height of the graph, which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18864 means that we must obtain this information here. Note that the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18865 @code{print-graph-body} function also requires this information. There |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18866 is no reason to calculate the height of the graph in two different |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18867 places, so we should change @code{print-graph-body} from the way we |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18868 defined it earlier to take advantage of the calculation. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18869 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18870 Similarly, both the function for printing the X axis labels and the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18871 @code{print-graph-body} function need to learn the value of the width of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18872 each symbol. We can perform the calculation here and change the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18873 definition for @code{print-graph-body} from the way we defined it in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18874 previous chapter. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18875 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18876 The length of the label for the horizontal axis must be at least as long |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18877 as the graph. However, this information is used only in the function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18878 that prints the horizontal axis, so it does not need to be calculated here. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18879 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18880 These thoughts lead us directly to the following form for the varlist |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18881 in the @code{let} for @code{print-graph}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18882 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18883 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18884 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18885 (let ((height (apply 'max numbers-list)) ; @r{First version.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18886 (symbol-width (length graph-blank))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18887 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18888 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18889 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18890 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18891 As we shall see, this expression is not quite right. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18892 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18893 @node print-Y-axis, print-X-axis, print-graph Varlist, Full Graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18894 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18895 @appendixsec The @code{print-Y-axis} Function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18896 @cindex Axis, print vertical |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18897 @cindex Y axis printing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18898 @cindex Vertical axis printing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18899 @cindex Print vertical axis |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18900 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18901 The job of the @code{print-Y-axis} function is to print a label for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18902 the vertical axis that looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18903 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18904 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18905 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18906 10 - |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18907 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18908 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18909 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18910 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18911 5 - |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18912 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18913 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18914 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18915 1 - |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18916 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18917 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18918 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18919 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18920 The function should be passed the height of the graph, and then should |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18921 construct and insert the appropriate numbers and marks. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18922 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18923 It is easy enough to see in the figure what the Y axis label should |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18924 look like; but to say in words, and then to write a function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18925 definition to do the job is another matter. It is not quite true to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18926 say that we want a number and a tic every five lines: there are only |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18927 three lines between the @samp{1} and the @samp{5} (lines 2, 3, and 4), |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18928 but four lines between the @samp{5} and the @samp{10} (lines 6, 7, 8, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18929 and 9). It is better to say that we want a number and a tic mark on |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18930 the base line (number 1) and then that we want a number and a tic on |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18931 the fifth line from the bottom and on every line that is a multiple of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18932 five. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18933 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18934 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18935 * Height of label:: What height for the Y axis? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18936 * Compute a Remainder:: How to compute the remainder of a division. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18937 * Y Axis Element:: Construct a line for the Y axis. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18938 * Y-axis-column:: Generate a list of Y axis labels. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18939 * print-Y-axis Penultimate:: A not quite final version. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18940 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18941 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18942 @node Height of label, Compute a Remainder, print-Y-axis, print-Y-axis |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18943 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18944 @unnumberedsubsec What height should the label be? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18945 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18946 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18947 The next issue is what height the label should be? Suppose the maximum |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18948 height of tallest column of the graph is seven. Should the highest |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18949 label on the Y axis be @samp{5 -}, and should the graph stick up above |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18950 the label? Or should the highest label be @samp{7 -}, and mark the peak |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18951 of the graph? Or should the highest label be @code{10 -}, which is a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18952 multiple of five, and be higher than the topmost value of the graph? |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18953 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18954 The latter form is preferred. Most graphs are drawn within rectangles |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18955 whose sides are an integral number of steps long---5, 10, 15, and so |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18956 on for a step distance of five. But as soon as we decide to use a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18957 step height for the vertical axis, we discover that the simple |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18958 expression in the varlist for computing the height is wrong. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18959 expression is @code{(apply 'max numbers-list)}. This returns the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18960 precise height, not the maximum height plus whatever is necessary to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18961 round up to the nearest multiple of five. A more complex expression |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18962 is required. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18963 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18964 As usual in cases like this, a complex problem becomes simpler if it is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18965 divided into several smaller problems. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18966 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18967 First, consider the case when the highest value of the graph is an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18968 integral multiple of five---when it is 5, 10, 15 ,or some higher |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18969 multiple of five. We can use this value as the Y axis height. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18970 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18971 A fairly simply way to determine whether a number is a multiple of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18972 five is to divide it by five and see if the division results in a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18973 remainder. If there is no remainder, the number is a multiple of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18974 five. Thus, seven divided by five has a remainder of two, and seven |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18975 is not an integral multiple of five. Put in slightly different |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18976 language, more reminiscent of the classroom, five goes into seven |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18977 once, with a remainder of two. However, five goes into ten twice, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18978 with no remainder: ten is an integral multiple of five. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18979 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18980 @node Compute a Remainder, Y Axis Element, Height of label, print-Y-axis |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18981 @appendixsubsec Side Trip: Compute a Remainder |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18982 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18983 @findex % @r{(remainder function)} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18984 @cindex Remainder function, @code{%} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18985 In Lisp, the function for computing a remainder is @code{%}. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18986 function returns the remainder of its first argument divided by its |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18987 second argument. As it happens, @code{%} is a function in Emacs Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18988 that you cannot discover using @code{apropos}: you find nothing if you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18989 type @kbd{M-x apropos @key{RET} remainder @key{RET}}. The only way to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18990 learn of the existence of @code{%} is to read about it in a book such |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18991 as this or in the Emacs Lisp sources. The @code{%} function is used |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18992 in the code for @code{rotate-yank-pointer}, which is described in an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18993 appendix. (@xref{rotate-yk-ptr body, , The Body of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18994 @code{rotate-yank-pointer}}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18995 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18996 You can try the @code{%} function by evaluating the following two |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18997 expressions: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18998 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
18999 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19000 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19001 (% 7 5) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19002 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19003 (% 10 5) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19004 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19005 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19006 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19007 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19008 The first expression returns 2 and the second expression returns 0. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19009 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19010 To test whether the returned value is zero or some other number, we |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19011 can use the @code{zerop} function. This function returns @code{t} if |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19012 its argument, which must be a number, is zero. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19013 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19014 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19015 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19016 (zerop (% 7 5)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19017 @result{} nil |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19018 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19019 (zerop (% 10 5)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19020 @result{} t |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19021 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19022 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19023 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19024 Thus, the following expression will return @code{t} if the height |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19025 of the graph is evenly divisible by five: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19026 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19027 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19028 (zerop (% height 5)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19029 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19030 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19031 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19032 (The value of @code{height}, of course, can be found from @code{(apply |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19033 'max numbers-list)}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19034 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19035 On the other hand, if the value of @code{height} is not a multiple of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19036 five, we want to reset the value to the next higher multiple of five. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19037 This is straightforward arithmetic using functions with which we are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19038 already familiar. First, we divide the value of @code{height} by five |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19039 to determine how many times five goes into the number. Thus, five |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19040 goes into twelve twice. If we add one to this quotient and multiply by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19041 five, we will obtain the value of the next multiple of five that is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19042 larger than the height. Five goes into twelve twice. Add one to two, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19043 and multiply by five; the result is fifteen, which is the next multiple |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19044 of five that is higher than twelve. The Lisp expression for this is: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19045 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19046 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19047 (* (1+ (/ height 5)) 5) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19048 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19049 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19050 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19051 For example, if you evaluate the following, the result is 15: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19052 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19053 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19054 (* (1+ (/ 12 5)) 5) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19055 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19056 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19057 All through this discussion, we have been using `five' as the value |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19058 for spacing labels on the Y axis; but we may want to use some other |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19059 value. For generality, we should replace `five' with a variable to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19060 which we can assign a value. The best name I can think of for this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19061 variable is @code{Y-axis-label-spacing}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19062 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19063 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19064 Using this term, and an @code{if} expression, we produce the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19065 following: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19066 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19067 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19068 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19069 (if (zerop (% height Y-axis-label-spacing)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19070 height |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19071 ;; @r{else} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19072 (* (1+ (/ height Y-axis-label-spacing)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19073 Y-axis-label-spacing)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19074 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19075 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19076 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19077 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19078 This expression returns the value of @code{height} itself if the height |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19079 is an even multiple of the value of the @code{Y-axis-label-spacing} or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19080 else it computes and returns a value of @code{height} that is equal to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19081 the next higher multiple of the value of the @code{Y-axis-label-spacing}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19082 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19083 We can now include this expression in the @code{let} expression of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19084 @code{print-graph} function (after first setting the value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19085 @code{Y-axis-label-spacing}): |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19086 @vindex Y-axis-label-spacing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19087 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19088 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19089 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19090 (defvar Y-axis-label-spacing 5 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19091 "Number of lines from one Y axis label to next.") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19092 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19093 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19094 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19095 @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19096 (let* ((height (apply 'max numbers-list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19097 (height-of-top-line |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19098 (if (zerop (% height Y-axis-label-spacing)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19099 height |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19100 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19101 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19102 ;; @r{else} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19103 (* (1+ (/ height Y-axis-label-spacing)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19104 Y-axis-label-spacing))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19105 (symbol-width (length graph-blank)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19106 @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19107 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19108 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19109 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19110 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19111 (Note use of the @code{let*} function: the initial value of height is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19112 computed once by the @code{(apply 'max numbers-list)} expression and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19113 then the resulting value of @code{height} is used to compute its |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19114 final value. @xref{fwd-para let, , The @code{let*} expression}, for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19115 more about @code{let*}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19116 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19117 @node Y Axis Element, Y-axis-column, Compute a Remainder, print-Y-axis |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19118 @appendixsubsec Construct a Y Axis Element |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19119 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19120 When we print the vertical axis, we want to insert strings such as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19121 @w{@samp{5 -}} and @w{@samp{10 - }} every five lines. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19122 Moreover, we want the numbers and dashes to line up, so shorter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19123 numbers must be padded with leading spaces. If some of the strings |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19124 use two digit numbers, the strings with single digit numbers must |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19125 include a leading blank space before the number. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19126 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19127 @findex number-to-string |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19128 To figure out the length of the number, the @code{length} function is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19129 used. But the @code{length} function works only with a string, not with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19130 a number. So the number has to be converted from being a number to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19131 being a string. This is done with the @code{number-to-string} function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19132 For example, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19133 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19134 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19135 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19136 (length (number-to-string 35)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19137 @result{} 2 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19138 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19139 (length (number-to-string 100)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19140 @result{} 3 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19141 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19142 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19143 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19144 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19145 (@code{number-to-string} is also called @code{int-to-string}; you will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19146 see this alternative name in various sources.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19147 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19148 In addition, in each label, each number is followed by a string such |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19149 as @w{@samp{ - }}, which we will call the @code{Y-axis-tic} marker. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19150 This variable is defined with @code{defvar}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19151 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19152 @vindex Y-axis-tic |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19153 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19154 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19155 (defvar Y-axis-tic " - " |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19156 "String that follows number in a Y axis label.") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19157 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19158 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19159 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19160 The length of the Y label is the sum of the length of the Y axis tic |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19161 mark and the length of the number of the top of the graph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19162 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19163 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19164 (length (concat (number-to-string height) Y-axis-tic))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19165 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19166 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19167 This value will be calculated by the @code{print-graph} function in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19168 its varlist as @code{full-Y-label-width} and passed on. (Note that we |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19169 did not think to include this in the varlist when we first proposed it.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19170 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19171 To make a complete vertical axis label, a tic mark is concatenated |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19172 with a number; and the two together may be preceded by one or more |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19173 spaces depending on how long the number is. The label consists of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19174 three parts: the (optional) leading spaces, the number, and the tic |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19175 mark. The function is passed the value of the number for the specific |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19176 row, and the value of the width of the top line, which is calculated |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19177 (just once) by @code{print-graph}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19178 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19179 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19180 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19181 (defun Y-axis-element (number full-Y-label-width) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19182 "Construct a NUMBERed label element. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19183 A numbered element looks like this ` 5 - ', |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19184 and is padded as needed so all line up with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19185 the element for the largest number." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19186 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19187 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19188 (let* ((leading-spaces |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19189 (- full-Y-label-width |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19190 (length |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19191 (concat (number-to-string number) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19192 Y-axis-tic))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19193 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19194 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19195 (concat |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19196 (make-string leading-spaces ? ) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19197 (number-to-string number) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19198 Y-axis-tic))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19199 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19200 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19201 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19202 The @code{Y-axis-element} function concatenates together the leading |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19203 spaces, if any; the number, as a string; and the tic mark. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19204 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19205 To figure out how many leading spaces the label will need, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19206 function subtracts the actual length of the label---the length of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19207 number plus the length of the tic mark---from the desired label width. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19208 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19209 @findex make-string |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19210 Blank spaces are inserted using the @code{make-string} function. This |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19211 function takes two arguments: the first tells it how long the string |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19212 will be and the second is a symbol for the character to insert, in a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19213 special format. The format is a question mark followed by a blank |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19214 space, like this, @samp{? }. @xref{Character Type, , Character Type, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19215 elisp, The GNU Emacs Lisp Reference Manual}, for a description of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19216 syntax for characters. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19217 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19218 The @code{number-to-string} function is used in the concatenation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19219 expression, to convert the number to a string that is concatenated |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19220 with the leading spaces and the tic mark. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19221 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19222 @node Y-axis-column, print-Y-axis Penultimate, Y Axis Element, print-Y-axis |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19223 @appendixsubsec Create a Y Axis Column |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19224 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19225 The preceding functions provide all the tools needed to construct a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19226 function that generates a list of numbered and blank strings to insert |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19227 as the label for the vertical axis: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19228 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19229 @findex Y-axis-column |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19230 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19231 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19232 (defun Y-axis-column (height width-of-label) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19233 "Construct list of Y axis labels and blank strings. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19234 For HEIGHT of line above base and WIDTH-OF-LABEL." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19235 (let (Y-axis) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19236 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19237 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19238 (while (> height 1) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19239 (if (zerop (% height Y-axis-label-spacing)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19240 ;; @r{Insert label.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19241 (setq Y-axis |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19242 (cons |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19243 (Y-axis-element height width-of-label) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19244 Y-axis)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19245 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19246 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19247 ;; @r{Else, insert blanks.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19248 (setq Y-axis |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19249 (cons |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19250 (make-string width-of-label ? ) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19251 Y-axis))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19252 (setq height (1- height))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19253 ;; @r{Insert base line.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19254 (setq Y-axis |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19255 (cons (Y-axis-element 1 width-of-label) Y-axis)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19256 (nreverse Y-axis))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19257 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19258 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19259 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19260 In this function, we start with the value of @code{height} and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19261 repetitively subtract one from its value. After each subtraction, we |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19262 test to see whether the value is an integral multiple of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19263 @code{Y-axis-label-spacing}. If it is, we construct a numbered label |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19264 using the @code{Y-axis-element} function; if not, we construct a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19265 blank label using the @code{make-string} function. The base line |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19266 consists of the number one followed by a tic mark. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19267 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19268 @node print-Y-axis Penultimate, , Y-axis-column, print-Y-axis |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19269 @appendixsubsec The Not Quite Final Version of @code{print-Y-axis} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19270 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19271 The list constructed by the @code{Y-axis-column} function is passed to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19272 the @code{print-Y-axis} function, which inserts the list as a column. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19273 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19274 @findex print-Y-axis |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19275 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19276 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19277 (defun print-Y-axis (height full-Y-label-width) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19278 "Insert Y axis using HEIGHT and FULL-Y-LABEL-WIDTH. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19279 Height must be the maximum height of the graph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19280 Full width is the width of the highest label element." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19281 ;; Value of height and full-Y-label-width |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19282 ;; are passed by `print-graph'. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19283 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19284 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19285 (let ((start (point))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19286 (insert-rectangle |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19287 (Y-axis-column height full-Y-label-width)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19288 ;; @r{Place point ready for inserting graph.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19289 (goto-char start) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19290 ;; @r{Move point forward by value of} full-Y-label-width |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19291 (forward-char full-Y-label-width))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19292 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19293 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19294 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19295 The @code{print-Y-axis} uses the @code{insert-rectangle} function to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19296 insert the Y axis labels created by the @code{Y-axis-column} function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19297 In addition, it places point at the correct position for printing the body of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19298 the graph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19299 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19300 You can test @code{print-Y-axis}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19301 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19302 @enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19303 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19304 Install |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19305 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19306 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19307 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19308 Y-axis-label-spacing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19309 Y-axis-tic |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19310 Y-axis-element |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19311 Y-axis-column |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19312 print-Y-axis |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19313 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19314 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19315 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19316 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19317 Copy the following expression: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19318 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19319 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19320 (print-Y-axis 12 5) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19321 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19322 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19323 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19324 Switch to the @file{*scratch*} buffer and place the cursor where you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19325 want the axis labels to start. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19326 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19327 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19328 Type @kbd{M-:} (@code{eval-expression}). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19329 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19330 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19331 Yank the @code{graph-body-print} expression into the minibuffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19332 with @kbd{C-y} (@code{yank)}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19333 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19334 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19335 Press @key{RET} to evaluate the expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19336 @end enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19337 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19338 Emacs will print labels vertically, the top one being |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19339 @w{@samp{10 -@w{ }}}. (The @code{print-graph} function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19340 will pass the value of @code{height-of-top-line}, which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19341 in this case would end up as 15.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19342 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19343 @node print-X-axis, Print Whole Graph, print-Y-axis, Full Graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19344 @appendixsec The @code{print-X-axis} Function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19345 @cindex Axis, print horizontal |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19346 @cindex X axis printing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19347 @cindex Print horizontal axis |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19348 @cindex Horizontal axis printing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19349 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19350 X axis labels are much like Y axis labels, except that the tics are on a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19351 line above the numbers. Labels should look like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19352 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19353 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19354 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19355 | | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19356 1 5 10 15 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19357 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19358 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19359 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19360 The first tic is under the first column of the graph and is preceded by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19361 several blank spaces. These spaces provide room in rows above for the Y |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19362 axis labels. The second, third, fourth, and subsequent tics are all |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19363 spaced equally, according to the value of @code{X-axis-label-spacing}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19364 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19365 The second row of the X axis consists of numbers, preceded by several |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19366 blank spaces and also separated according to the value of the variable |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19367 @code{X-axis-label-spacing}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19368 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19369 The value of the variable @code{X-axis-label-spacing} should itself be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19370 measured in units of @code{symbol-width}, since you may want to change |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19371 the width of the symbols that you are using to print the body of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19372 graph without changing the ways the graph is labelled. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19373 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19374 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19375 * Similarities differences:: Much like @code{print-Y-axis}, but not exactly. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19376 * X Axis Tic Marks:: Create tic marks for the horizontal axis. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19377 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19378 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19379 @node Similarities differences, X Axis Tic Marks, print-X-axis, print-X-axis |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19380 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19381 @unnumberedsubsec Similarities and differences |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19382 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19383 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19384 The @code{print-X-axis} function is constructed in more or less the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19385 same fashion as the @code{print-Y-axis} function except that it has |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19386 two lines: the line of tic marks and the numbers. We will write a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19387 separate function to print each line and then combine them within the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19388 @code{print-X-axis} function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19389 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19390 This is a three step process: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19391 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19392 @enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19393 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19394 Write a function to print the X axis tic marks, @code{print-X-axis-tic-line}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19395 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19396 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19397 Write a function to print the X numbers, @code{print-X-axis-numbered-line}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19398 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19399 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19400 Write a function to print both lines, the @code{print-X-axis} function, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19401 using @code{print-X-axis-tic-line} and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19402 @code{print-X-axis-numbered-line}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19403 @end enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19404 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19405 @node X Axis Tic Marks, , Similarities differences, print-X-axis |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19406 @appendixsubsec X Axis Tic Marks |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19407 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19408 The first function should print the X axis tic marks. We must specify |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19409 the tic marks themselves and their spacing: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19410 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19411 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19412 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19413 (defvar X-axis-label-spacing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19414 (if (boundp 'graph-blank) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19415 (* 5 (length graph-blank)) 5) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19416 "Number of units from one X axis label to next.") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19417 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19418 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19419 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19420 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19421 (Note that the value of @code{graph-blank} is set by another |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19422 @code{defvar}. The @code{boundp} predicate checks whether it has |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19423 already been set; @code{boundp} returns @code{nil} if it has not. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19424 If @code{graph-blank} were unbound and we did not use this conditional |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19425 construction, in GNU Emacs 21, we would enter the debugger and see an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19426 error message saying |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19427 @samp{@w{Debugger entered--Lisp error:} @w{(void-variable graph-blank)}}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19428 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19429 @need 1200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19430 Here is the @code{defvar} for @code{X-axis-tic-symbol}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19431 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19432 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19433 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19434 (defvar X-axis-tic-symbol "|" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19435 "String to insert to point to a column in X axis.") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19436 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19437 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19438 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19439 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19440 The goal is to make a line that looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19441 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19442 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19443 | | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19444 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19445 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19446 The first tic is indented so that it is under the first column, which is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19447 indented to provide space for the Y axis labels. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19448 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19449 A tic element consists of the blank spaces that stretch from one tic to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19450 the next plus a tic symbol. The number of blanks is determined by the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19451 width of the tic symbol and the @code{X-axis-label-spacing}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19452 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19453 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19454 The code looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19455 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19456 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19457 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19458 ;;; X-axis-tic-element |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19459 @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19460 (concat |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19461 (make-string |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19462 ;; @r{Make a string of blanks.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19463 (- (* symbol-width X-axis-label-spacing) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19464 (length X-axis-tic-symbol)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19465 ? ) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19466 ;; @r{Concatenate blanks with tic symbol.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19467 X-axis-tic-symbol) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19468 @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19469 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19470 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19471 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19472 Next, we determine how many blanks are needed to indent the first tic |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19473 mark to the first column of the graph. This uses the value of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19474 @code{full-Y-label-width} passed it by the @code{print-graph} function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19475 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19476 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19477 The code to make @code{X-axis-leading-spaces} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19478 looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19479 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19480 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19481 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19482 ;; X-axis-leading-spaces |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19483 @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19484 (make-string full-Y-label-width ? ) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19485 @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19486 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19487 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19488 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19489 We also need to determine the length of the horizontal axis, which is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19490 the length of the numbers list, and the number of tics in the horizontal |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19491 axis: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19492 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19493 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19494 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19495 ;; X-length |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19496 @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19497 (length numbers-list) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19498 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19499 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19500 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19501 ;; tic-width |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19502 @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19503 (* symbol-width X-axis-label-spacing) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19504 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19505 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19506 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19507 ;; number-of-X-tics |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19508 (if (zerop (% (X-length tic-width))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19509 (/ (X-length tic-width)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19510 (1+ (/ (X-length tic-width)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19511 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19512 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19513 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19514 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19515 All this leads us directly to the function for printing the X axis tic line: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19516 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19517 @findex print-X-axis-tic-line |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19518 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19519 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19520 (defun print-X-axis-tic-line |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19521 (number-of-X-tics X-axis-leading-spaces X-axis-tic-element) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19522 "Print tics for X axis." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19523 (insert X-axis-leading-spaces) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19524 (insert X-axis-tic-symbol) ; @r{Under first column.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19525 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19526 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19527 ;; @r{Insert second tic in the right spot.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19528 (insert (concat |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19529 (make-string |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19530 (- (* symbol-width X-axis-label-spacing) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19531 ;; @r{Insert white space up to second tic symbol.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19532 (* 2 (length X-axis-tic-symbol))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19533 ? ) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19534 X-axis-tic-symbol)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19535 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19536 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19537 ;; @r{Insert remaining tics.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19538 (while (> number-of-X-tics 1) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19539 (insert X-axis-tic-element) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19540 (setq number-of-X-tics (1- number-of-X-tics)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19541 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19542 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19543 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19544 The line of numbers is equally straightforward: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19545 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19546 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19547 First, we create a numbered element with blank spaces before each number: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19548 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19549 @findex X-axis-element |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19550 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19551 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19552 (defun X-axis-element (number) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19553 "Construct a numbered X axis element." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19554 (let ((leading-spaces |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19555 (- (* symbol-width X-axis-label-spacing) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19556 (length (number-to-string number))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19557 (concat (make-string leading-spaces ? ) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19558 (number-to-string number)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19559 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19560 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19561 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19562 Next, we create the function to print the numbered line, starting with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19563 the number ``1'' under the first column: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19564 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19565 @findex print-X-axis-numbered-line |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19566 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19567 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19568 (defun print-X-axis-numbered-line |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19569 (number-of-X-tics X-axis-leading-spaces) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19570 "Print line of X-axis numbers" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19571 (let ((number X-axis-label-spacing)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19572 (insert X-axis-leading-spaces) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19573 (insert "1") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19574 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19575 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19576 (insert (concat |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19577 (make-string |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19578 ;; @r{Insert white space up to next number.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19579 (- (* symbol-width X-axis-label-spacing) 2) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19580 ? ) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19581 (number-to-string number))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19582 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19583 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19584 ;; @r{Insert remaining numbers.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19585 (setq number (+ number X-axis-label-spacing)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19586 (while (> number-of-X-tics 1) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19587 (insert (X-axis-element number)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19588 (setq number (+ number X-axis-label-spacing)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19589 (setq number-of-X-tics (1- number-of-X-tics))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19590 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19591 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19592 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19593 Finally, we need to write the @code{print-X-axis} that uses |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19594 @code{print-X-axis-tic-line} and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19595 @code{print-X-axis-numbered-line}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19596 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19597 The function must determine the local values of the variables used by both |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19598 @code{print-X-axis-tic-line} and @code{print-X-axis-numbered-line}, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19599 then it must call them. Also, it must print the carriage return that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19600 separates the two lines. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19601 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19602 The function consists of a varlist that specifies five local variables, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19603 and calls to each of the two line printing functions: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19604 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19605 @findex print-X-axis |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19606 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19607 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19608 (defun print-X-axis (numbers-list) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19609 "Print X axis labels to length of NUMBERS-LIST." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19610 (let* ((leading-spaces |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19611 (make-string full-Y-label-width ? )) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19612 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19613 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19614 ;; symbol-width @r{is provided by} graph-body-print |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19615 (tic-width (* symbol-width X-axis-label-spacing)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19616 (X-length (length numbers-list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19617 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19618 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19619 (X-tic |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19620 (concat |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19621 (make-string |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19622 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19623 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19624 ;; @r{Make a string of blanks.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19625 (- (* symbol-width X-axis-label-spacing) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19626 (length X-axis-tic-symbol)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19627 ? ) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19628 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19629 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19630 ;; @r{Concatenate blanks with tic symbol.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19631 X-axis-tic-symbol)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19632 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19633 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19634 (tic-number |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19635 (if (zerop (% X-length tic-width)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19636 (/ X-length tic-width) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19637 (1+ (/ X-length tic-width))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19638 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19639 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19640 (print-X-axis-tic-line tic-number leading-spaces X-tic) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19641 (insert "\n") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19642 (print-X-axis-numbered-line tic-number leading-spaces))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19643 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19644 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19645 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19646 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19647 You can test @code{print-X-axis}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19648 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19649 @enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19650 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19651 Install @code{X-axis-tic-symbol}, @code{X-axis-label-spacing}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19652 @code{print-X-axis-tic-line}, as well as @code{X-axis-element}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19653 @code{print-X-axis-numbered-line}, and @code{print-X-axis}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19654 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19655 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19656 Copy the following expression: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19657 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19658 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19659 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19660 (progn |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19661 (let ((full-Y-label-width 5) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19662 (symbol-width 1)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19663 (print-X-axis |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19664 '(1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19665 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19666 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19667 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19668 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19669 Switch to the @file{*scratch*} buffer and place the cursor where you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19670 want the axis labels to start. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19671 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19672 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19673 Type @kbd{M-:} (@code{eval-expression}). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19674 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19675 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19676 Yank the test expression into the minibuffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19677 with @kbd{C-y} (@code{yank)}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19678 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19679 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19680 Press @key{RET} to evaluate the expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19681 @end enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19682 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19683 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19684 Emacs will print the horizontal axis like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19685 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19686 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19687 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19688 | | | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19689 1 5 10 15 20 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19690 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19691 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19692 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19693 @node Print Whole Graph, , print-X-axis, Full Graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19694 @appendixsec Printing the Whole Graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19695 @cindex Printing the whole graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19696 @cindex Whole graph printing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19697 @cindex Graph, printing all |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19698 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19699 Now we are nearly ready to print the whole graph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19700 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19701 The function to print the graph with the proper labels follows the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19702 outline we created earlier (@pxref{Full Graph, , A Graph with Labelled |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19703 Axes}), but with additions. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19704 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19705 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19706 Here is the outline: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19707 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19708 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19709 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19710 (defun print-graph (numbers-list) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19711 "@var{documentation}@dots{}" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19712 (let ((height @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19713 @dots{})) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19714 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19715 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19716 (print-Y-axis height @dots{} ) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19717 (graph-body-print numbers-list) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19718 (print-X-axis @dots{} ))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19719 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19720 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19721 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19722 @menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19723 * The final version:: A few changes. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19724 * Test print-graph:: Run a short test. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19725 * Graphing words in defuns:: Executing the final code. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19726 * lambda:: How to write an anonymous function. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19727 * mapcar:: Apply a function to elements of a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19728 * Another Bug:: Yet another bug @dots{} most insidious. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19729 * Final printed graph:: The graph itself! |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19730 @end menu |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19731 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19732 @node The final version, Test print-graph, Print Whole Graph, Print Whole Graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19733 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19734 @unnumberedsubsec Changes for the Final Version |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19735 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19736 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19737 The final version is different from what we planned in two ways: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19738 first, it contains additional values calculated once in the varlist; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19739 second, it carries an option to specify the labels' increment per row. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19740 This latter feature turns out to be essential; otherwise, a graph may |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19741 have more rows than fit on a display or on a sheet of paper. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19742 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19743 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19744 This new feature requires a change to the @code{Y-axis-column} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19745 function, to add @code{vertical-step} to it. The function looks like |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19746 this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19747 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19748 @findex Y-axis-column @r{Final version.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19749 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19750 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19751 ;;; @r{Final version.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19752 (defun Y-axis-column |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19753 (height width-of-label &optional vertical-step) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19754 "Construct list of labels for Y axis. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19755 HEIGHT is maximum height of graph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19756 WIDTH-OF-LABEL is maximum width of label. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19757 VERTICAL-STEP, an option, is a positive integer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19758 that specifies how much a Y axis label increments |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19759 for each line. For example, a step of 5 means |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19760 that each line is five units of the graph." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19761 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19762 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19763 (let (Y-axis |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19764 (number-per-line (or vertical-step 1))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19765 (while (> height 1) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19766 (if (zerop (% height Y-axis-label-spacing)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19767 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19768 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19769 ;; @r{Insert label.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19770 (setq Y-axis |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19771 (cons |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19772 (Y-axis-element |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19773 (* height number-per-line) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19774 width-of-label) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19775 Y-axis)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19776 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19777 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19778 ;; @r{Else, insert blanks.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19779 (setq Y-axis |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19780 (cons |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19781 (make-string width-of-label ? ) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19782 Y-axis))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19783 (setq height (1- height))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19784 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19785 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19786 ;; @r{Insert base line.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19787 (setq Y-axis (cons (Y-axis-element |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19788 (or vertical-step 1) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19789 width-of-label) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19790 Y-axis)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19791 (nreverse Y-axis))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19792 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19793 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19794 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19795 The values for the maximum height of graph and the width of a symbol |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19796 are computed by @code{print-graph} in its @code{let} expression; so |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19797 @code{graph-body-print} must be changed to accept them. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19798 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19799 @findex graph-body-print @r{Final version.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19800 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19801 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19802 ;;; @r{Final version.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19803 (defun graph-body-print (numbers-list height symbol-width) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19804 "Print a bar graph of the NUMBERS-LIST. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19805 The numbers-list consists of the Y-axis values. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19806 HEIGHT is maximum height of graph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19807 SYMBOL-WIDTH is number of each column." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19808 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19809 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19810 (let (from-position) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19811 (while numbers-list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19812 (setq from-position (point)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19813 (insert-rectangle |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19814 (column-of-graph height (car numbers-list))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19815 (goto-char from-position) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19816 (forward-char symbol-width) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19817 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19818 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19819 ;; @r{Draw graph column by column.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19820 (sit-for 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19821 (setq numbers-list (cdr numbers-list))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19822 ;; @r{Place point for X axis labels.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19823 (forward-line height) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19824 (insert "\n"))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19825 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19826 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19827 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19828 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19829 Finally, the code for the @code{print-graph} function: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19830 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19831 @findex print-graph @r{Final version.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19832 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19833 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19834 ;;; @r{Final version.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19835 (defun print-graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19836 (numbers-list &optional vertical-step) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19837 "Print labelled bar graph of the NUMBERS-LIST. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19838 The numbers-list consists of the Y-axis values. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19839 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19840 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19841 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19842 Optionally, VERTICAL-STEP, a positive integer, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19843 specifies how much a Y axis label increments for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19844 each line. For example, a step of 5 means that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19845 each row is five units." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19846 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19847 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19848 (let* ((symbol-width (length graph-blank)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19849 ;; @code{height} @r{is both the largest number} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19850 ;; @r{and the number with the most digits.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19851 (height (apply 'max numbers-list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19852 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19853 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19854 (height-of-top-line |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19855 (if (zerop (% height Y-axis-label-spacing)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19856 height |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19857 ;; @r{else} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19858 (* (1+ (/ height Y-axis-label-spacing)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19859 Y-axis-label-spacing))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19860 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19861 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19862 (vertical-step (or vertical-step 1)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19863 (full-Y-label-width |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19864 (length |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19865 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19866 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19867 (concat |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19868 (number-to-string |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19869 (* height-of-top-line vertical-step)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19870 Y-axis-tic)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19871 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19872 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19873 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19874 (print-Y-axis |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19875 height-of-top-line full-Y-label-width vertical-step) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19876 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19877 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19878 (graph-body-print |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19879 numbers-list height-of-top-line symbol-width) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19880 (print-X-axis numbers-list))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19881 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19882 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19883 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19884 @node Test print-graph, Graphing words in defuns, The final version, Print Whole Graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19885 @appendixsubsec Testing @code{print-graph} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19886 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19887 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19888 We can test the @code{print-graph} function with a short list of numbers: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19889 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19890 @enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19891 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19892 Install the final versions of @code{Y-axis-column}, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19893 @code{graph-body-print}, and @code{print-graph} (in addition to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19894 rest of the code.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19895 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19896 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19897 Copy the following expression: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19898 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19899 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19900 (print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19901 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19902 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19903 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19904 Switch to the @file{*scratch*} buffer and place the cursor where you |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19905 want the axis labels to start. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19906 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19907 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19908 Type @kbd{M-:} (@code{eval-expression}). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19909 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19910 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19911 Yank the test expression into the minibuffer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19912 with @kbd{C-y} (@code{yank)}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19913 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19914 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19915 Press @key{RET} to evaluate the expression. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19916 @end enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19917 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19918 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19919 Emacs will print a graph that looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19920 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19921 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19922 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19923 10 - |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19924 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19925 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19926 * |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19927 ** * |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19928 5 - **** * |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19929 **** *** |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19930 * ********* |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19931 ************ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19932 1 - ************* |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19933 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19934 | | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19935 1 5 10 15 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19936 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19937 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19938 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19939 On the other hand, if you pass @code{print-graph} a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19940 @code{vertical-step} value of 2, by evaluating this expression: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19941 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19942 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19943 (print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1) 2) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19944 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19945 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19946 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19947 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19948 The graph looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19949 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19950 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19951 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19952 20 - |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19953 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19954 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19955 * |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19956 ** * |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19957 10 - **** * |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19958 **** *** |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19959 * ********* |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19960 ************ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19961 2 - ************* |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19962 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19963 | | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19964 1 5 10 15 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19965 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19966 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19967 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19968 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19969 (A question: is the `2' on the bottom of the vertical axis a bug or a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19970 feature? If you think it is a bug, and should be a `1' instead, (or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19971 even a `0'), you can modify the sources.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19972 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19973 @node Graphing words in defuns, lambda, Test print-graph, Print Whole Graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19974 @appendixsubsec Graphing Numbers of Words and Symbols |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19975 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19976 Now for the graph for which all this code was written: a graph that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19977 shows how many function definitions contain fewer than 10 words and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19978 symbols, how many contain between 10 and 19 words and symbols, how |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19979 many contain between 20 and 29 words and symbols, and so on. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19980 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19981 This is a multi-step process. First make sure you have loaded all the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19982 requisite code. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19983 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19984 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19985 It is a good idea to reset the value of @code{top-of-ranges} in case |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19986 you have set it to some different value. You can evaluate the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19987 following: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19988 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19989 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19990 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19991 (setq top-of-ranges |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19992 '(10 20 30 40 50 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19993 60 70 80 90 100 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19994 110 120 130 140 150 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19995 160 170 180 190 200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19996 210 220 230 240 250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19997 260 270 280 290 300) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19998 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
19999 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20000 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20001 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20002 Next create a list of the number of words and symbols in each range. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20003 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20004 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20005 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20006 Evaluate the following: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20007 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20008 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20009 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20010 (setq list-for-graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20011 (defuns-per-range |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20012 (sort |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20013 (recursive-lengths-list-many-files |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20014 (directory-files "/usr/local/emacs/lisp" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20015 t ".+el$")) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20016 '<) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20017 top-of-ranges)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20018 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20019 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20020 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20021 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20022 On my machine, this takes about an hour. It looks though 303 Lisp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20023 files in my copy of Emacs version 19.23. After all that computing, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20024 the @code{list-for-graph} has this value: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20025 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20026 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20027 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20028 (537 1027 955 785 594 483 349 292 224 199 166 120 116 99 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20029 90 80 67 48 52 45 41 33 28 26 25 20 12 28 11 13 220) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20030 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20031 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20032 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20033 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20034 This means that my copy of Emacs has 537 function definitions with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20035 fewer than 10 words or symbols in them, 1,027 function definitions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20036 with 10 to 19 words or symbols in them, 955 function definitions with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20037 20 to 29 words or symbols in them, and so on. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20038 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20039 Clearly, just by looking at this list we can see that most function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20040 definitions contain ten to thirty words and symbols. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20041 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20042 Now for printing. We do @emph{not} want to print a graph that is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20043 1,030 lines high @dots{} Instead, we should print a graph that is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20044 fewer than twenty-five lines high. A graph that height can be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20045 displayed on almost any monitor, and easily printed on a sheet of paper. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20046 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20047 This means that each value in @code{list-for-graph} must be reduced to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20048 one-fiftieth its present value. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20049 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20050 Here is a short function to do just that, using two functions we have |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20051 not yet seen, @code{mapcar} and @code{lambda}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20052 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20053 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20054 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20055 (defun one-fiftieth (full-range) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20056 "Return list, each number one-fiftieth of previous." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20057 (mapcar '(lambda (arg) (/ arg 50)) full-range)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20058 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20059 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20060 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20061 @node lambda, mapcar, Graphing words in defuns, Print Whole Graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20062 @appendixsubsec A @code{lambda} Expression: Useful Anonymity |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20063 @cindex Anonymous function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20064 @findex lambda |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20065 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20066 @code{lambda} is the symbol for an anonymous function, a function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20067 without a name. Every time you use an anonymous function, you need to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20068 include its whole body. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20069 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20070 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20071 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20072 Thus, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20073 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20074 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20075 (lambda (arg) (/ arg 50)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20076 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20077 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20078 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20079 is a function definition that says `return the value resulting from |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20080 dividing whatever is passed to me as @code{arg} by 50'. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20081 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20082 Earlier, for example, we had a function @code{multiply-by-seven}; it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20083 multiplied its argument by 7. This function is similar, except it |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20084 divides its argument by 50; and, it has no name. The anonymous |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20085 equivalent of @code{multiply-by-seven} is: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20086 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20087 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20088 (lambda (number) (* 7 number)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20089 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20090 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20091 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20092 (@xref{defun, , The @code{defun} Special Form}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20093 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20094 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20095 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20096 If we want to multiply 3 by 7, we can write: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20097 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20098 @c !!! Clear print-postscript-figures if the computer formatting this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20099 @c document is too small and cannot handle all the diagrams and figures. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20100 @c clear print-postscript-figures |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20101 @c set print-postscript-figures |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20102 @c lambda example diagram #1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20103 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20104 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20105 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20106 (multiply-by-seven 3) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20107 \_______________/ ^ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20108 | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20109 function argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20110 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20111 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20112 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20113 @ifset print-postscript-figures |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20114 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20115 @tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20116 @image{lambda-1} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20117 %%%% old method of including an image |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20118 % \input /usr/local/lib/tex/inputs/psfig.tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20119 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-1.eps}} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20120 % \catcode`\@=0 % |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20121 @end tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20122 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20123 @end ifset |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20124 @ifclear print-postscript-figures |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20125 @iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20126 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20127 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20128 (multiply-by-seven 3) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20129 \_______________/ ^ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20130 | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20131 function argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20132 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20133 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20134 @end iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20135 @end ifclear |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20136 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20137 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20138 This expression returns 21. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20139 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20140 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20141 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20142 Similarly, we can write: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20143 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20144 @c lambda example diagram #2 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20145 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20146 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20147 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20148 ((lambda (number) (* 7 number)) 3) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20149 \____________________________/ ^ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20150 | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20151 anonymous function argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20152 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20153 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20154 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20155 @ifset print-postscript-figures |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20156 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20157 @tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20158 @image{lambda-2} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20159 %%%% old method of including an image |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20160 % \input /usr/local/lib/tex/inputs/psfig.tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20161 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-2.eps}} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20162 % \catcode`\@=0 % |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20163 @end tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20164 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20165 @end ifset |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20166 @ifclear print-postscript-figures |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20167 @iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20168 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20169 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20170 ((lambda (number) (* 7 number)) 3) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20171 \____________________________/ ^ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20172 | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20173 anonymous function argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20174 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20175 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20176 @end iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20177 @end ifclear |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20178 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20179 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20180 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20181 If we want to divide 100 by 50, we can write: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20182 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20183 @c lambda example diagram #3 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20184 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20185 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20186 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20187 ((lambda (arg) (/ arg 50)) 100) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20188 \______________________/ \_/ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20189 | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20190 anonymous function argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20191 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20192 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20193 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20194 @ifset print-postscript-figures |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20195 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20196 @tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20197 @image{lambda-3} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20198 %%%% old method of including an image |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20199 % \input /usr/local/lib/tex/inputs/psfig.tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20200 % \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-3.eps}} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20201 % \catcode`\@=0 % |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20202 @end tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20203 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20204 @end ifset |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20205 @ifclear print-postscript-figures |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20206 @iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20207 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20208 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20209 ((lambda (arg) (/ arg 50)) 100) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20210 \______________________/ \_/ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20211 | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20212 anonymous function argument |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20213 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20214 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20215 @end iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20216 @end ifclear |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20217 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20218 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20219 This expression returns 2. The 100 is passed to the function, which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20220 divides that number by 50. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20221 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20222 @xref{Lambda Expressions, , Lambda Expressions, elisp, The GNU Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20223 Lisp Reference Manual}, for more about @code{lambda}. Lisp and lambda |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20224 expressions derive from the Lambda Calculus. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20225 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20226 @node mapcar, Another Bug, lambda, Print Whole Graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20227 @appendixsubsec The @code{mapcar} Function |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20228 @findex mapcar |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20229 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20230 @code{mapcar} is a function that calls its first argument with each |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20231 element of its second argument, in turn. The second argument must be |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20232 a sequence. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20233 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20234 The @samp{map} part of the name comes from the mathematical phrase, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20235 `mapping over a domain', meaning to apply a function to each of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20236 elements in a domain. The mathematical phrase is based on the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20237 metaphor of a surveyor walking, one step at a time, over an area he is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20238 mapping. And @samp{car}, of course, comes from the Lisp notion of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20239 first of a list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20240 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20241 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20242 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20243 For example, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20244 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20245 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20246 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20247 (mapcar '1+ '(2 4 6)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20248 @result{} (3 5 7) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20249 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20250 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20251 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20252 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20253 The function @code{1+} which adds one to its argument, is executed on |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20254 @emph{each} element of the list, and a new list is returned. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20255 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20256 Contrast this with @code{apply}, which applies its first argument to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20257 all the remaining. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20258 (@xref{Readying a Graph, , Readying a Graph}, for a explanation of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20259 @code{apply}.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20260 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20261 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20262 In the definition of @code{one-fiftieth}, the first argument is the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20263 anonymous function: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20264 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20265 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20266 (lambda (arg) (/ arg 50)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20267 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20268 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20269 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20270 and the second argument is @code{full-range}, which will be bound to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20271 @code{list-for-graph}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20272 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20273 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20274 The whole expression looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20275 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20276 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20277 (mapcar '(lambda (arg) (/ arg 50)) full-range)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20278 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20279 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20280 @xref{Mapping Functions, , Mapping Functions, elisp, The GNU Emacs |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20281 Lisp Reference Manual}, for more about @code{mapcar}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20282 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20283 Using the @code{one-fiftieth} function, we can generate a list in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20284 which each element is one-fiftieth the size of the corresponding |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20285 element in @code{list-for-graph}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20286 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20287 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20288 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20289 (setq fiftieth-list-for-graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20290 (one-fiftieth list-for-graph)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20291 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20292 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20293 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20294 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20295 The resulting list looks like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20296 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20297 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20298 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20299 (10 20 19 15 11 9 6 5 4 3 3 2 2 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20300 1 1 1 1 0 1 0 0 0 0 0 0 0 0 0 0 0 4) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20301 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20302 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20303 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20304 @noindent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20305 This, we are almost ready to print! (We also notice the loss of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20306 information: many of the higher ranges are 0, meaning that fewer than |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20307 50 defuns had that many words or symbols---but not necessarily meaning |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20308 that none had that many words or symbols.) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20309 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20310 @node Another Bug, Final printed graph, mapcar, Print Whole Graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20311 @appendixsubsec Another Bug @dots{} Most Insidious |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20312 @cindex Bug, most insidious type |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20313 @cindex Insidious type of bug |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20314 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20315 I said `almost ready to print'! Of course, there is a bug in the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20316 @code{print-graph} function @dots{} It has a @code{vertical-step} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20317 option, but not a @code{horizontal-step} option. The |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20318 @code{top-of-range} scale goes from 10 to 300 by tens. But the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20319 @code{print-graph} function will print only by ones. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20320 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20321 This is a classic example of what some consider the most insidious |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20322 type of bug, the bug of omission. This is not the kind of bug you can |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20323 find by studying the code, for it is not in the code; it is an omitted |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20324 feature. Your best actions are to try your program early and often; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20325 and try to arrange, as much as you can, to write code that is easy to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20326 understand and easy to change. Try to be aware, whenever you can, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20327 that whatever you have written, @emph{will} be rewritten, if not soon, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20328 eventually. A hard maxim to follow. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20329 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20330 It is the @code{print-X-axis-numbered-line} function that needs the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20331 work; and then the @code{print-X-axis} and the @code{print-graph} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20332 functions need to be adapted. Not much needs to be done; there is one |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20333 nicety: the numbers ought to line up under the tic marks. This takes |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20334 a little thought. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20335 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20336 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20337 Here is the corrected @code{print-X-axis-numbered-line}: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20338 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20339 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20340 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20341 (defun print-X-axis-numbered-line |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20342 (number-of-X-tics X-axis-leading-spaces |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20343 &optional horizontal-step) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20344 "Print line of X-axis numbers" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20345 (let ((number X-axis-label-spacing) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20346 (horizontal-step (or horizontal-step 1))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20347 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20348 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20349 (insert X-axis-leading-spaces) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20350 ;; @r{Delete extra leading spaces.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20351 (delete-char |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20352 (- (1- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20353 (length (number-to-string horizontal-step))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20354 (insert (concat |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20355 (make-string |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20356 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20357 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20358 ;; @r{Insert white space.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20359 (- (* symbol-width |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20360 X-axis-label-spacing) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20361 (1- |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20362 (length |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20363 (number-to-string horizontal-step))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20364 2) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20365 ? ) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20366 (number-to-string |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20367 (* number horizontal-step)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20368 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20369 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20370 ;; @r{Insert remaining numbers.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20371 (setq number (+ number X-axis-label-spacing)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20372 (while (> number-of-X-tics 1) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20373 (insert (X-axis-element |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20374 (* number horizontal-step))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20375 (setq number (+ number X-axis-label-spacing)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20376 (setq number-of-X-tics (1- number-of-X-tics))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20377 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20378 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20379 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20380 @need 1500 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20381 If you are reading this in Info, you can see the new versions of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20382 @code{print-X-axis} @code{print-graph} and evaluate them. If you are |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20383 reading this in a printed book, you can see the changed lines here |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20384 (the full text is too much to print). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20385 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20386 @iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20387 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20388 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20389 (defun print-X-axis (numbers-list horizontal-step) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20390 @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20391 (print-X-axis-numbered-line |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20392 tic-number leading-spaces horizontal-step)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20393 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20394 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20395 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20396 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20397 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20398 (defun print-graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20399 (numbers-list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20400 &optional vertical-step horizontal-step) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20401 @dots{} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20402 (print-X-axis numbers-list horizontal-step)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20403 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20404 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20405 @end iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20406 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20407 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20408 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20409 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20410 (defun print-X-axis (numbers-list horizontal-step) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20411 "Print X axis labels to length of NUMBERS-LIST. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20412 Optionally, HORIZONTAL-STEP, a positive integer, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20413 specifies how much an X axis label increments for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20414 each column." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20415 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20416 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20417 ;; Value of symbol-width and full-Y-label-width |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20418 ;; are passed by `print-graph'. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20419 (let* ((leading-spaces |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20420 (make-string full-Y-label-width ? )) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20421 ;; symbol-width @r{is provided by} graph-body-print |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20422 (tic-width (* symbol-width X-axis-label-spacing)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20423 (X-length (length numbers-list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20424 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20425 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20426 (X-tic |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20427 (concat |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20428 (make-string |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20429 ;; @r{Make a string of blanks.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20430 (- (* symbol-width X-axis-label-spacing) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20431 (length X-axis-tic-symbol)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20432 ? ) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20433 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20434 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20435 ;; @r{Concatenate blanks with tic symbol.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20436 X-axis-tic-symbol)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20437 (tic-number |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20438 (if (zerop (% X-length tic-width)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20439 (/ X-length tic-width) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20440 (1+ (/ X-length tic-width))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20441 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20442 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20443 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20444 (print-X-axis-tic-line |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20445 tic-number leading-spaces X-tic) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20446 (insert "\n") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20447 (print-X-axis-numbered-line |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20448 tic-number leading-spaces horizontal-step))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20449 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20450 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20451 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20452 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20453 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20454 (defun print-graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20455 (numbers-list &optional vertical-step horizontal-step) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20456 "Print labelled bar graph of the NUMBERS-LIST. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20457 The numbers-list consists of the Y-axis values. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20458 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20459 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20460 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20461 Optionally, VERTICAL-STEP, a positive integer, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20462 specifies how much a Y axis label increments for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20463 each line. For example, a step of 5 means that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20464 each row is five units. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20465 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20466 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20467 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20468 Optionally, HORIZONTAL-STEP, a positive integer, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20469 specifies how much an X axis label increments for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20470 each column." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20471 (let* ((symbol-width (length graph-blank)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20472 ;; @code{height} @r{is both the largest number} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20473 ;; @r{and the number with the most digits.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20474 (height (apply 'max numbers-list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20475 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20476 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20477 (height-of-top-line |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20478 (if (zerop (% height Y-axis-label-spacing)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20479 height |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20480 ;; @r{else} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20481 (* (1+ (/ height Y-axis-label-spacing)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20482 Y-axis-label-spacing))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20483 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20484 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20485 (vertical-step (or vertical-step 1)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20486 (full-Y-label-width |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20487 (length |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20488 (concat |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20489 (number-to-string |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20490 (* height-of-top-line vertical-step)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20491 Y-axis-tic)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20492 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20493 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20494 (print-Y-axis |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20495 height-of-top-line full-Y-label-width vertical-step) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20496 (graph-body-print |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20497 numbers-list height-of-top-line symbol-width) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20498 (print-X-axis numbers-list horizontal-step))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20499 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20500 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20501 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20502 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20503 @ignore |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20504 Graphing Definitions Re-listed |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20505 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20506 @need 1250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20507 Here are all the graphing definitions in their final form: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20508 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20509 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20510 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20511 (defvar top-of-ranges |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20512 '(10 20 30 40 50 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20513 60 70 80 90 100 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20514 110 120 130 140 150 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20515 160 170 180 190 200 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20516 210 220 230 240 250) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20517 "List specifying ranges for `defuns-per-range'.") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20518 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20519 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20520 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20521 (defvar graph-symbol "*" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20522 "String used as symbol in graph, usually an asterisk.") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20523 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20524 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20525 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20526 (defvar graph-blank " " |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20527 "String used as blank in graph, usually a blank space. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20528 graph-blank must be the same number of columns wide |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20529 as graph-symbol.") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20530 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20531 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20532 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20533 (defvar Y-axis-tic " - " |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20534 "String that follows number in a Y axis label.") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20535 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20536 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20537 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20538 (defvar Y-axis-label-spacing 5 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20539 "Number of lines from one Y axis label to next.") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20540 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20541 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20542 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20543 (defvar X-axis-tic-symbol "|" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20544 "String to insert to point to a column in X axis.") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20545 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20546 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20547 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20548 (defvar X-axis-label-spacing |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20549 (if (boundp 'graph-blank) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20550 (* 5 (length graph-blank)) 5) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20551 "Number of units from one X axis label to next.") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20552 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20553 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20554 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20555 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20556 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20557 (defun count-words-in-defun () |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20558 "Return the number of words and symbols in a defun." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20559 (beginning-of-defun) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20560 (let ((count 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20561 (end (save-excursion (end-of-defun) (point)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20562 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20563 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20564 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20565 (while |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20566 (and (< (point) end) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20567 (re-search-forward |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20568 "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20569 end t)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20570 (setq count (1+ count))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20571 count)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20572 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20573 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20574 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20575 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20576 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20577 (defun lengths-list-file (filename) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20578 "Return list of definitions' lengths within FILE. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20579 The returned list is a list of numbers. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20580 Each number is the number of words or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20581 symbols in one function definition." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20582 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20583 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20584 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20585 (message "Working on `%s' ... " filename) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20586 (save-excursion |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20587 (let ((buffer (find-file-noselect filename)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20588 (lengths-list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20589 (set-buffer buffer) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20590 (setq buffer-read-only t) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20591 (widen) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20592 (goto-char (point-min)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20593 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20594 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20595 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20596 (while (re-search-forward "^(defun" nil t) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20597 (setq lengths-list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20598 (cons (count-words-in-defun) lengths-list))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20599 (kill-buffer buffer) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20600 lengths-list))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20601 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20602 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20603 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20604 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20605 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20606 (defun lengths-list-many-files (list-of-files) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20607 "Return list of lengths of defuns in LIST-OF-FILES." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20608 (let (lengths-list) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20609 ;;; @r{true-or-false-test} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20610 (while list-of-files |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20611 (setq lengths-list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20612 (append |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20613 lengths-list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20614 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20615 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20616 ;;; @r{Generate a lengths' list.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20617 (lengths-list-file |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20618 (expand-file-name (car list-of-files))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20619 ;;; @r{Make files' list shorter.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20620 (setq list-of-files (cdr list-of-files))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20621 ;;; @r{Return final value of lengths' list.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20622 lengths-list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20623 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20624 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20625 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20626 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20627 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20628 (defun defuns-per-range (sorted-lengths top-of-ranges) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20629 "SORTED-LENGTHS defuns in each TOP-OF-RANGES range." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20630 (let ((top-of-range (car top-of-ranges)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20631 (number-within-range 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20632 defuns-per-range-list) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20633 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20634 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20635 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20636 ;; @r{Outer loop.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20637 (while top-of-ranges |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20638 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20639 ;; @r{Inner loop.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20640 (while (and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20641 ;; @r{Need number for numeric test.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20642 (car sorted-lengths) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20643 (< (car sorted-lengths) top-of-range)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20644 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20645 ;; @r{Count number of definitions within current range.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20646 (setq number-within-range (1+ number-within-range)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20647 (setq sorted-lengths (cdr sorted-lengths))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20648 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20649 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20650 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20651 ;; @r{Exit inner loop but remain within outer loop.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20652 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20653 (setq defuns-per-range-list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20654 (cons number-within-range defuns-per-range-list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20655 (setq number-within-range 0) ; @r{Reset count to zero.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20656 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20657 ;; @r{Move to next range.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20658 (setq top-of-ranges (cdr top-of-ranges)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20659 ;; @r{Specify next top of range value.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20660 (setq top-of-range (car top-of-ranges))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20661 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20662 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20663 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20664 ;; @r{Exit outer loop and count the number of defuns larger than} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20665 ;; @r{ the largest top-of-range value.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20666 (setq defuns-per-range-list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20667 (cons |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20668 (length sorted-lengths) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20669 defuns-per-range-list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20670 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20671 ;; @r{Return a list of the number of definitions within each range,} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20672 ;; @r{ smallest to largest.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20673 (nreverse defuns-per-range-list))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20674 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20675 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20676 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20677 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20678 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20679 (defun column-of-graph (max-graph-height actual-height) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20680 "Return list of MAX-GRAPH-HEIGHT strings; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20681 ACTUAL-HEIGHT are graph-symbols. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20682 The graph-symbols are contiguous entries at the end |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20683 of the list. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20684 The list will be inserted as one column of a graph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20685 The strings are either graph-blank or graph-symbol." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20686 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20687 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20688 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20689 (let ((insert-list nil) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20690 (number-of-top-blanks |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20691 (- max-graph-height actual-height))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20692 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20693 ;; @r{Fill in @code{graph-symbols}.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20694 (while (> actual-height 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20695 (setq insert-list (cons graph-symbol insert-list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20696 (setq actual-height (1- actual-height))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20697 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20698 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20699 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20700 ;; @r{Fill in @code{graph-blanks}.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20701 (while (> number-of-top-blanks 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20702 (setq insert-list (cons graph-blank insert-list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20703 (setq number-of-top-blanks |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20704 (1- number-of-top-blanks))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20705 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20706 ;; @r{Return whole list.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20707 insert-list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20708 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20709 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20710 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20711 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20712 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20713 (defun Y-axis-element (number full-Y-label-width) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20714 "Construct a NUMBERed label element. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20715 A numbered element looks like this ` 5 - ', |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20716 and is padded as needed so all line up with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20717 the element for the largest number." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20718 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20719 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20720 (let* ((leading-spaces |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20721 (- full-Y-label-width |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20722 (length |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20723 (concat (number-to-string number) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20724 Y-axis-tic))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20725 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20726 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20727 (concat |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20728 (make-string leading-spaces ? ) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20729 (number-to-string number) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20730 Y-axis-tic))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20731 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20732 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20733 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20734 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20735 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20736 (defun print-Y-axis |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20737 (height full-Y-label-width &optional vertical-step) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20738 "Insert Y axis by HEIGHT and FULL-Y-LABEL-WIDTH. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20739 Height must be the maximum height of the graph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20740 Full width is the width of the highest label element. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20741 Optionally, print according to VERTICAL-STEP." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20742 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20743 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20744 ;; Value of height and full-Y-label-width |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20745 ;; are passed by `print-graph'. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20746 (let ((start (point))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20747 (insert-rectangle |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20748 (Y-axis-column height full-Y-label-width vertical-step)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20749 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20750 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20751 ;; @r{Place point ready for inserting graph.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20752 (goto-char start) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20753 ;; @r{Move point forward by value of} full-Y-label-width |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20754 (forward-char full-Y-label-width))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20755 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20756 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20757 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20758 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20759 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20760 (defun print-X-axis-tic-line |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20761 (number-of-X-tics X-axis-leading-spaces X-axis-tic-element) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20762 "Print tics for X axis." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20763 (insert X-axis-leading-spaces) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20764 (insert X-axis-tic-symbol) ; @r{Under first column.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20765 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20766 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20767 ;; @r{Insert second tic in the right spot.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20768 (insert (concat |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20769 (make-string |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20770 (- (* symbol-width X-axis-label-spacing) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20771 ;; @r{Insert white space up to second tic symbol.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20772 (* 2 (length X-axis-tic-symbol))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20773 ? ) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20774 X-axis-tic-symbol)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20775 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20776 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20777 ;; @r{Insert remaining tics.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20778 (while (> number-of-X-tics 1) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20779 (insert X-axis-tic-element) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20780 (setq number-of-X-tics (1- number-of-X-tics)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20781 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20782 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20783 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20784 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20785 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20786 (defun X-axis-element (number) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20787 "Construct a numbered X axis element." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20788 (let ((leading-spaces |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20789 (- (* symbol-width X-axis-label-spacing) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20790 (length (number-to-string number))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20791 (concat (make-string leading-spaces ? ) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20792 (number-to-string number)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20793 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20794 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20795 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20796 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20797 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20798 (defun graph-body-print (numbers-list height symbol-width) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20799 "Print a bar graph of the NUMBERS-LIST. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20800 The numbers-list consists of the Y-axis values. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20801 HEIGHT is maximum height of graph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20802 SYMBOL-WIDTH is number of each column." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20803 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20804 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20805 (let (from-position) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20806 (while numbers-list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20807 (setq from-position (point)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20808 (insert-rectangle |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20809 (column-of-graph height (car numbers-list))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20810 (goto-char from-position) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20811 (forward-char symbol-width) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20812 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20813 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20814 ;; @r{Draw graph column by column.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20815 (sit-for 0) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20816 (setq numbers-list (cdr numbers-list))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20817 ;; @r{Place point for X axis labels.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20818 (forward-line height) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20819 (insert "\n"))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20820 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20821 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20822 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20823 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20824 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20825 (defun Y-axis-column |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20826 (height width-of-label &optional vertical-step) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20827 "Construct list of labels for Y axis. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20828 HEIGHT is maximum height of graph. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20829 WIDTH-OF-LABEL is maximum width of label. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20830 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20831 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20832 VERTICAL-STEP, an option, is a positive integer |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20833 that specifies how much a Y axis label increments |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20834 for each line. For example, a step of 5 means |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20835 that each line is five units of the graph." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20836 (let (Y-axis |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20837 (number-per-line (or vertical-step 1))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20838 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20839 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20840 (while (> height 1) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20841 (if (zerop (% height Y-axis-label-spacing)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20842 ;; @r{Insert label.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20843 (setq Y-axis |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20844 (cons |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20845 (Y-axis-element |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20846 (* height number-per-line) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20847 width-of-label) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20848 Y-axis)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20849 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20850 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20851 ;; @r{Else, insert blanks.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20852 (setq Y-axis |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20853 (cons |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20854 (make-string width-of-label ? ) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20855 Y-axis))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20856 (setq height (1- height))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20857 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20858 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20859 ;; @r{Insert base line.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20860 (setq Y-axis (cons (Y-axis-element |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20861 (or vertical-step 1) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20862 width-of-label) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20863 Y-axis)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20864 (nreverse Y-axis))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20865 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20866 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20867 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20868 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20869 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20870 (defun print-X-axis-numbered-line |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20871 (number-of-X-tics X-axis-leading-spaces |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20872 &optional horizontal-step) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20873 "Print line of X-axis numbers" |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20874 (let ((number X-axis-label-spacing) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20875 (horizontal-step (or horizontal-step 1))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20876 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20877 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20878 (insert X-axis-leading-spaces) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20879 ;; line up number |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20880 (delete-char (- (1- (length (number-to-string horizontal-step))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20881 (insert (concat |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20882 (make-string |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20883 ;; @r{Insert white space up to next number.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20884 (- (* symbol-width X-axis-label-spacing) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20885 (1- (length (number-to-string horizontal-step))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20886 2) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20887 ? ) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20888 (number-to-string (* number horizontal-step)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20889 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20890 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20891 ;; @r{Insert remaining numbers.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20892 (setq number (+ number X-axis-label-spacing)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20893 (while (> number-of-X-tics 1) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20894 (insert (X-axis-element (* number horizontal-step))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20895 (setq number (+ number X-axis-label-spacing)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20896 (setq number-of-X-tics (1- number-of-X-tics))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20897 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20898 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20899 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20900 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20901 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20902 (defun print-X-axis (numbers-list horizontal-step) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20903 "Print X axis labels to length of NUMBERS-LIST. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20904 Optionally, HORIZONTAL-STEP, a positive integer, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20905 specifies how much an X axis label increments for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20906 each column." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20907 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20908 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20909 ;; Value of symbol-width and full-Y-label-width |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20910 ;; are passed by `print-graph'. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20911 (let* ((leading-spaces |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20912 (make-string full-Y-label-width ? )) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20913 ;; symbol-width @r{is provided by} graph-body-print |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20914 (tic-width (* symbol-width X-axis-label-spacing)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20915 (X-length (length numbers-list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20916 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20917 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20918 (X-tic |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20919 (concat |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20920 (make-string |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20921 ;; @r{Make a string of blanks.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20922 (- (* symbol-width X-axis-label-spacing) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20923 (length X-axis-tic-symbol)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20924 ? ) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20925 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20926 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20927 ;; @r{Concatenate blanks with tic symbol.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20928 X-axis-tic-symbol)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20929 (tic-number |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20930 (if (zerop (% X-length tic-width)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20931 (/ X-length tic-width) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20932 (1+ (/ X-length tic-width))))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20933 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20934 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20935 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20936 (print-X-axis-tic-line |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20937 tic-number leading-spaces X-tic) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20938 (insert "\n") |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20939 (print-X-axis-numbered-line |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20940 tic-number leading-spaces horizontal-step))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20941 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20942 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20943 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20944 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20945 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20946 (defun one-fiftieth (full-range) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20947 "Return list, each number of which is 1/50th previous." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20948 (mapcar '(lambda (arg) (/ arg 50)) full-range)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20949 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20950 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20951 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20952 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20953 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20954 (defun print-graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20955 (numbers-list &optional vertical-step horizontal-step) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20956 "Print labelled bar graph of the NUMBERS-LIST. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20957 The numbers-list consists of the Y-axis values. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20958 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20959 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20960 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20961 Optionally, VERTICAL-STEP, a positive integer, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20962 specifies how much a Y axis label increments for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20963 each line. For example, a step of 5 means that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20964 each row is five units. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20965 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20966 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20967 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20968 Optionally, HORIZONTAL-STEP, a positive integer, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20969 specifies how much an X axis label increments for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20970 each column." |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20971 (let* ((symbol-width (length graph-blank)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20972 ;; @code{height} @r{is both the largest number} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20973 ;; @r{and the number with the most digits.} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20974 (height (apply 'max numbers-list)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20975 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20976 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20977 (height-of-top-line |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20978 (if (zerop (% height Y-axis-label-spacing)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20979 height |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20980 ;; @r{else} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20981 (* (1+ (/ height Y-axis-label-spacing)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20982 Y-axis-label-spacing))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20983 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20984 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20985 (vertical-step (or vertical-step 1)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20986 (full-Y-label-width |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20987 (length |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20988 (concat |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20989 (number-to-string |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20990 (* height-of-top-line vertical-step)) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20991 Y-axis-tic)))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20992 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20993 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20994 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20995 (print-Y-axis |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20996 height-of-top-line full-Y-label-width vertical-step) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20997 (graph-body-print |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20998 numbers-list height-of-top-line symbol-width) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
20999 (print-X-axis numbers-list horizontal-step))) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21000 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21001 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21002 @end ignore |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21003 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21004 @page |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21005 @node Final printed graph, , Another Bug, Print Whole Graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21006 @appendixsubsec The Printed Graph |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21007 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21008 When made and installed, you can call the @code{print-graph} command |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21009 like this: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21010 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21011 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21012 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21013 (print-graph fiftieth-list-for-graph 50 10) |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21014 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21015 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21016 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21017 Here is the graph: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21018 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21019 @sp 2 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21020 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21021 @smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21022 @group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21023 1000 - * |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21024 ** |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21025 ** |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21026 ** |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21027 ** |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21028 750 - *** |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21029 *** |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21030 *** |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21031 *** |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21032 **** |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21033 500 - ***** |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21034 ****** |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21035 ****** |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21036 ****** |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21037 ******* |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21038 250 - ******** |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21039 ********* * |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21040 *********** * |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21041 ************* * |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21042 50 - ***************** * * |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21043 | | | | | | | | |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21044 10 50 100 150 200 250 300 350 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21045 @end group |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21046 @end smallexample |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21047 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21048 @sp 2 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21049 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21050 The largest group of functions contain 10 -- 19 words and symbols each. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21051 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21052 @node GNU Free Documentation License, Index, Full Graph, Top |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21053 @appendix GNU Free Documentation License |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21054 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21055 @cindex FDL, GNU Free Documentation License |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21056 @center Version 1.1, March 2000 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21057 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21058 @display |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21059 Copyright @copyright{} 2000 Free Software Foundation, Inc. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21060 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21061 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21062 Everyone is permitted to copy and distribute verbatim copies |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21063 of this license document, but changing it is not allowed. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21064 @end display |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21065 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21066 @enumerate 0 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21067 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21068 PREAMBLE |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21069 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21070 The purpose of this License is to make a manual, textbook, or other |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21071 written document @dfn{free} in the sense of freedom: to assure everyone |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21072 the effective freedom to copy and redistribute it, with or without |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21073 modifying it, either commercially or noncommercially. Secondarily, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21074 this License preserves for the author and publisher a way to get |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21075 credit for their work, while not being considered responsible for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21076 modifications made by others. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21077 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21078 This License is a kind of ``copyleft'', which means that derivative |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21079 works of the document must themselves be free in the same sense. It |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21080 complements the GNU General Public License, which is a copyleft |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21081 license designed for free software. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21082 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21083 We have designed this License in order to use it for manuals for free |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21084 software, because free software needs free documentation: a free |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21085 program should come with manuals providing the same freedoms that the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21086 software does. But this License is not limited to software manuals; |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21087 it can be used for any textual work, regardless of subject matter or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21088 whether it is published as a printed book. We recommend this License |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21089 principally for works whose purpose is instruction or reference. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21090 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21091 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21092 APPLICABILITY AND DEFINITIONS |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21093 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21094 This License applies to any manual or other work that contains a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21095 notice placed by the copyright holder saying it can be distributed |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21096 under the terms of this License. The ``Document'', below, refers to any |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21097 such manual or work. Any member of the public is a licensee, and is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21098 addressed as ``you''. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21099 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21100 A ``Modified Version'' of the Document means any work containing the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21101 Document or a portion of it, either copied verbatim, or with |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21102 modifications and/or translated into another language. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21103 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21104 A ``Secondary Section'' is a named appendix or a front-matter section of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21105 the Document that deals exclusively with the relationship of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21106 publishers or authors of the Document to the Document's overall subject |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21107 (or to related matters) and contains nothing that could fall directly |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21108 within that overall subject. (For example, if the Document is in part a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21109 textbook of mathematics, a Secondary Section may not explain any |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21110 mathematics.) The relationship could be a matter of historical |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21111 connection with the subject or with related matters, or of legal, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21112 commercial, philosophical, ethical or political position regarding |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21113 them. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21114 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21115 The ``Invariant Sections'' are certain Secondary Sections whose titles |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21116 are designated, as being those of Invariant Sections, in the notice |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21117 that says that the Document is released under this License. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21118 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21119 The ``Cover Texts'' are certain short passages of text that are listed, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21120 as Front-Cover Texts or Back-Cover Texts, in the notice that says that |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21121 the Document is released under this License. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21122 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21123 A ``Transparent'' copy of the Document means a machine-readable copy, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21124 represented in a format whose specification is available to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21125 general public, whose contents can be viewed and edited directly and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21126 straightforwardly with generic text editors or (for images composed of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21127 pixels) generic paint programs or (for drawings) some widely available |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21128 drawing editor, and that is suitable for input to text formatters or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21129 for automatic translation to a variety of formats suitable for input |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21130 to text formatters. A copy made in an otherwise Transparent file |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21131 format whose markup has been designed to thwart or discourage |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21132 subsequent modification by readers is not Transparent. A copy that is |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21133 not ``Transparent'' is called ``Opaque''. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21134 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21135 Examples of suitable formats for Transparent copies include plain |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21136 @sc{ascii} without markup, Texinfo input format, La@TeX{} input format, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21137 @acronym{SGML} or @acronym{XML} using a publicly available |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21138 @acronym{DTD}, and standard-conforming simple @acronym{HTML} designed |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21139 for human modification. Opaque formats include PostScript, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21140 @acronym{PDF}, proprietary formats that can be read and edited only by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21141 proprietary word processors, @acronym{SGML} or @acronym{XML} for which |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21142 the @acronym{DTD} and/or processing tools are not generally available, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21143 and the machine-generated @acronym{HTML} produced by some word |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21144 processors for output purposes only. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21145 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21146 The ``Title Page'' means, for a printed book, the title page itself, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21147 plus such following pages as are needed to hold, legibly, the material |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21148 this License requires to appear in the title page. For works in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21149 formats which do not have any title page as such, ``Title Page'' means |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21150 the text near the most prominent appearance of the work's title, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21151 preceding the beginning of the body of the text. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21152 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21153 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21154 VERBATIM COPYING |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21155 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21156 You may copy and distribute the Document in any medium, either |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21157 commercially or noncommercially, provided that this License, the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21158 copyright notices, and the license notice saying this License applies |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21159 to the Document are reproduced in all copies, and that you add no other |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21160 conditions whatsoever to those of this License. You may not use |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21161 technical measures to obstruct or control the reading or further |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21162 copying of the copies you make or distribute. However, you may accept |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21163 compensation in exchange for copies. If you distribute a large enough |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21164 number of copies you must also follow the conditions in section 3. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21165 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21166 You may also lend copies, under the same conditions stated above, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21167 you may publicly display copies. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21168 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21169 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21170 COPYING IN QUANTITY |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21171 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21172 If you publish printed copies of the Document numbering more than 100, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21173 and the Document's license notice requires Cover Texts, you must enclose |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21174 the copies in covers that carry, clearly and legibly, all these Cover |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21175 Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21176 the back cover. Both covers must also clearly and legibly identify |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21177 you as the publisher of these copies. The front cover must present |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21178 the full title with all words of the title equally prominent and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21179 visible. You may add other material on the covers in addition. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21180 Copying with changes limited to the covers, as long as they preserve |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21181 the title of the Document and satisfy these conditions, can be treated |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21182 as verbatim copying in other respects. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21183 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21184 If the required texts for either cover are too voluminous to fit |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21185 legibly, you should put the first ones listed (as many as fit |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21186 reasonably) on the actual cover, and continue the rest onto adjacent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21187 pages. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21188 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21189 If you publish or distribute Opaque copies of the Document numbering |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21190 more than 100, you must either include a machine-readable Transparent |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21191 copy along with each Opaque copy, or state in or with each Opaque copy |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21192 a publicly-accessible computer-network location containing a complete |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21193 Transparent copy of the Document, free of added material, which the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21194 general network-using public has access to download anonymously at no |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21195 charge using public-standard network protocols. If you use the latter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21196 option, you must take reasonably prudent steps, when you begin |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21197 distribution of Opaque copies in quantity, to ensure that this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21198 Transparent copy will remain thus accessible at the stated location |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21199 until at least one year after the last time you distribute an Opaque |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21200 copy (directly or through your agents or retailers) of that edition to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21201 the public. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21202 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21203 It is requested, but not required, that you contact the authors of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21204 Document well before redistributing any large number of copies, to give |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21205 them a chance to provide you with an updated version of the Document. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21206 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21207 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21208 MODIFICATIONS |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21209 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21210 You may copy and distribute a Modified Version of the Document under |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21211 the conditions of sections 2 and 3 above, provided that you release |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21212 the Modified Version under precisely this License, with the Modified |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21213 Version filling the role of the Document, thus licensing distribution |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21214 and modification of the Modified Version to whoever possesses a copy |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21215 of it. In addition, you must do these things in the Modified Version: |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21216 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21217 @enumerate A |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21218 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21219 Use in the Title Page (and on the covers, if any) a title distinct |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21220 from that of the Document, and from those of previous versions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21221 (which should, if there were any, be listed in the History section |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21222 of the Document). You may use the same title as a previous version |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21223 if the original publisher of that version gives permission. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21224 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21225 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21226 List on the Title Page, as authors, one or more persons or entities |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21227 responsible for authorship of the modifications in the Modified |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21228 Version, together with at least five of the principal authors of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21229 Document (all of its principal authors, if it has less than five). |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21230 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21231 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21232 State on the Title page the name of the publisher of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21233 Modified Version, as the publisher. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21234 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21235 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21236 Preserve all the copyright notices of the Document. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21237 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21238 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21239 Add an appropriate copyright notice for your modifications |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21240 adjacent to the other copyright notices. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21241 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21242 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21243 Include, immediately after the copyright notices, a license notice |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21244 giving the public permission to use the Modified Version under the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21245 terms of this License, in the form shown in the Addendum below. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21246 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21247 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21248 Preserve in that license notice the full lists of Invariant Sections |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21249 and required Cover Texts given in the Document's license notice. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21250 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21251 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21252 Include an unaltered copy of this License. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21253 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21254 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21255 Preserve the section entitled ``History'', and its title, and add to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21256 it an item stating at least the title, year, new authors, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21257 publisher of the Modified Version as given on the Title Page. If |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21258 there is no section entitled ``History'' in the Document, create one |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21259 stating the title, year, authors, and publisher of the Document as |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21260 given on its Title Page, then add an item describing the Modified |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21261 Version as stated in the previous sentence. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21262 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21263 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21264 Preserve the network location, if any, given in the Document for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21265 public access to a Transparent copy of the Document, and likewise |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21266 the network locations given in the Document for previous versions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21267 it was based on. These may be placed in the ``History'' section. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21268 You may omit a network location for a work that was published at |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21269 least four years before the Document itself, or if the original |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21270 publisher of the version it refers to gives permission. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21271 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21272 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21273 In any section entitled ``Acknowledgments'' or ``Dedications'', |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21274 preserve the section's title, and preserve in the section all the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21275 substance and tone of each of the contributor acknowledgments |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21276 and/or dedications given therein. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21277 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21278 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21279 Preserve all the Invariant Sections of the Document, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21280 unaltered in their text and in their titles. Section numbers |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21281 or the equivalent are not considered part of the section titles. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21282 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21283 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21284 Delete any section entitled ``Endorsements''. Such a section |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21285 may not be included in the Modified Version. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21286 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21287 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21288 Do not retitle any existing section as ``Endorsements'' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21289 or to conflict in title with any Invariant Section. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21290 @end enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21291 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21292 If the Modified Version includes new front-matter sections or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21293 appendices that qualify as Secondary Sections and contain no material |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21294 copied from the Document, you may at your option designate some or all |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21295 of these sections as invariant. To do this, add their titles to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21296 list of Invariant Sections in the Modified Version's license notice. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21297 These titles must be distinct from any other section titles. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21298 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21299 You may add a section entitled ``Endorsements'', provided it contains |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21300 nothing but endorsements of your Modified Version by various |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21301 parties---for example, statements of peer review or that the text has |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21302 been approved by an organization as the authoritative definition of a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21303 standard. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21304 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21305 You may add a passage of up to five words as a Front-Cover Text, and a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21306 passage of up to 25 words as a Back-Cover Text, to the end of the list |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21307 of Cover Texts in the Modified Version. Only one passage of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21308 Front-Cover Text and one of Back-Cover Text may be added by (or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21309 through arrangements made by) any one entity. If the Document already |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21310 includes a cover text for the same cover, previously added by you or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21311 by arrangement made by the same entity you are acting on behalf of, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21312 you may not add another; but you may replace the old one, on explicit |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21313 permission from the previous publisher that added the old one. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21314 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21315 The author(s) and publisher(s) of the Document do not by this License |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21316 give permission to use their names for publicity for or to assert or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21317 imply endorsement of any Modified Version. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21318 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21319 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21320 COMBINING DOCUMENTS |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21321 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21322 You may combine the Document with other documents released under this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21323 License, under the terms defined in section 4 above for modified |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21324 versions, provided that you include in the combination all of the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21325 Invariant Sections of all of the original documents, unmodified, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21326 list them all as Invariant Sections of your combined work in its |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21327 license notice. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21328 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21329 The combined work need only contain one copy of this License, and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21330 multiple identical Invariant Sections may be replaced with a single |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21331 copy. If there are multiple Invariant Sections with the same name but |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21332 different contents, make the title of each such section unique by |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21333 adding at the end of it, in parentheses, the name of the original |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21334 author or publisher of that section if known, or else a unique number. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21335 Make the same adjustment to the section titles in the list of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21336 Invariant Sections in the license notice of the combined work. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21337 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21338 In the combination, you must combine any sections entitled ``History'' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21339 in the various original documents, forming one section entitled |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21340 ``History''; likewise combine any sections entitled ``Acknowledgments'', |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21341 and any sections entitled ``Dedications''. You must delete all sections |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21342 entitled ``Endorsements.'' |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21343 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21344 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21345 COLLECTIONS OF DOCUMENTS |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21346 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21347 You may make a collection consisting of the Document and other documents |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21348 released under this License, and replace the individual copies of this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21349 License in the various documents with a single copy that is included in |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21350 the collection, provided that you follow the rules of this License for |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21351 verbatim copying of each of the documents in all other respects. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21352 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21353 You may extract a single document from such a collection, and distribute |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21354 it individually under this License, provided you insert a copy of this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21355 License into the extracted document, and follow this License in all |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21356 other respects regarding verbatim copying of that document. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21357 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21358 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21359 AGGREGATION WITH INDEPENDENT WORKS |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21360 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21361 A compilation of the Document or its derivatives with other separate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21362 and independent documents or works, in or on a volume of a storage or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21363 distribution medium, does not as a whole count as a Modified Version |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21364 of the Document, provided no compilation copyright is claimed for the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21365 compilation. Such a compilation is called an ``aggregate'', and this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21366 License does not apply to the other self-contained works thus compiled |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21367 with the Document, on account of their being thus compiled, if they |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21368 are not themselves derivative works of the Document. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21369 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21370 If the Cover Text requirement of section 3 is applicable to these |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21371 copies of the Document, then if the Document is less than one quarter |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21372 of the entire aggregate, the Document's Cover Texts may be placed on |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21373 covers that surround only the Document within the aggregate. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21374 Otherwise they must appear on covers around the whole aggregate. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21375 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21376 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21377 TRANSLATION |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21378 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21379 Translation is considered a kind of modification, so you may |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21380 distribute translations of the Document under the terms of section 4. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21381 Replacing Invariant Sections with translations requires special |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21382 permission from their copyright holders, but you may include |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21383 translations of some or all Invariant Sections in addition to the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21384 original versions of these Invariant Sections. You may include a |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21385 translation of this License provided that you also include the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21386 original English version of this License. In case of a disagreement |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21387 between the translation and the original English version of this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21388 License, the original English version will prevail. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21389 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21390 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21391 TERMINATION |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21392 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21393 You may not copy, modify, sublicense, or distribute the Document except |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21394 as expressly provided for under this License. Any other attempt to |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21395 copy, modify, sublicense or distribute the Document is void, and will |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21396 automatically terminate your rights under this License. However, |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21397 parties who have received copies, or rights, from you under this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21398 License will not have their licenses terminated so long as such |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21399 parties remain in full compliance. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21400 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21401 @item |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21402 FUTURE REVISIONS OF THIS LICENSE |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21403 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21404 The Free Software Foundation may publish new, revised versions |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21405 of the GNU Free Documentation License from time to time. Such new |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21406 versions will be similar in spirit to the present version, but may |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21407 differ in detail to address new problems or concerns. See |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21408 @uref{http://www.gnu.org/copyleft/}. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21409 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21410 Each version of the License is given a distinguishing version number. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21411 If the Document specifies that a particular numbered version of this |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21412 License ``or any later version'' applies to it, you have the option of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21413 following the terms and conditions either of that specified version or |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21414 of any later version that has been published (not as a draft) by the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21415 Free Software Foundation. If the Document does not specify a version |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21416 number of this License, you may choose any version ever published (not |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21417 as a draft) by the Free Software Foundation. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21418 @end enumerate |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21419 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21420 @node Index, About the Author, GNU Free Documentation License, Top |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21421 @comment node-name, next, previous, up |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21422 @unnumbered Index |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21423 |
41670
b4c633081255
(Index): @ignore extraneous text.
Eli Zaretskii <eliz@gnu.org>
parents:
41499
diff
changeset
|
21424 @ignore |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21425 MENU ENTRY: NODE NAME. |
41670
b4c633081255
(Index): @ignore extraneous text.
Eli Zaretskii <eliz@gnu.org>
parents:
41499
diff
changeset
|
21426 @end ignore |
41421
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21427 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21428 @printindex cp |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21429 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21430 @iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21431 @c Place biographical information on right-hand (verso) page |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21432 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21433 @tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21434 \ifodd\pageno |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21435 \par\vfill\supereject |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21436 \global\evenheadline={\hfil} \global\evenfootline={\hfil} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21437 \global\oddheadline={\hfil} \global\oddfootline={\hfil} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21438 \page\hbox{}\page |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21439 \else |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21440 \par\vfill\supereject |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21441 \par\vfill\supereject |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21442 \global\evenheadline={\hfil} \global\evenfootline={\hfil} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21443 \global\oddheadline={\hfil} \global\oddfootline={\hfil} |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21444 \page\hbox{}\page |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21445 \page\hbox{}\page |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21446 \fi |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21447 @end tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21448 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21449 @page |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21450 @w{ } |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21451 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21452 @c ================ Biographical information ================ |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21453 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21454 @w{ } |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21455 @sp 8 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21456 @center About the Author |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21457 @sp 1 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21458 @end iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21459 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21460 @ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21461 @node About the Author, , Index, Top |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21462 @unnumbered About the Author |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21463 @end ifnottex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21464 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21465 @quotation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21466 Robert J. Chassell has worked with GNU Emacs since 1985. He writes |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21467 and edits, teaches Emacs and Emacs Lisp, and speaks throughout the |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21468 world on software freedom. Chassell was a founding Director and |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21469 Treasurer of the Free Software Foundation, Inc. He is co-author of |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21470 the @cite{Texinfo} manual, and has edited more than a dozen other |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21471 books. He graduated from Cambridge University, in England. He has an |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21472 abiding interest in social and economic history and flies his own |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21473 airplane. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21474 @end quotation |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21475 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21476 @page |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21477 @w{ } |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21478 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21479 @c Prevent page number on blank verso, so eject it first. |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21480 @tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21481 \par\vfill\supereject |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21482 @end tex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21483 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21484 @iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21485 @headings off |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21486 @evenheading @thispage @| @| @thistitle |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21487 @oddheading @| @| @thispage |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21488 @end iftex |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21489 |
7a66b17d124d
Modified slightly for inclusion in the Emacs distribution.
Eli Zaretskii <eliz@gnu.org>
parents:
diff
changeset
|
21490 @bye |