Mercurial > emacs
annotate lispref/intro.texi @ 69892:ec3278dd3d95
(Mail Sending): In send-mail-function @pxref smtpmail, put info and printed
manual names the right way around.
author | Eli Zaretskii <eliz@gnu.org> |
---|---|
date | Sun, 09 Apr 2006 18:44:06 +0000 |
parents | 067115a6e738 |
children | 5565c9588f39 c5406394f567 |
rev | line source |
---|---|
6453 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
64889
e836425ee789
Update years in copyright notice; nfc.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
63213
diff
changeset
|
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 2002, 2003, 2004, |
68648
067115a6e738
Update years in copyright notice; nfc.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
65328
diff
changeset
|
4 @c 2005, 2006 Free Software Foundation, Inc. |
6453 | 5 @c See the file elisp.texi for copying conditions. |
6 @setfilename ../info/intro | |
7 | |
29256 | 8 @node Introduction, Lisp Data Types, Top, Top |
6453 | 9 @comment node-name, next, previous, up |
10 @chapter Introduction | |
11 | |
12 Most of the GNU Emacs text editor is written in the programming | |
13 language called Emacs Lisp. You can write new code in Emacs Lisp and | |
14 install it as an extension to the editor. However, Emacs Lisp is more | |
15 than a mere ``extension language''; it is a full computer programming | |
16 language in its own right. You can use it as you would any other | |
17 programming language. | |
18 | |
19 Because Emacs Lisp is designed for use in an editor, it has special | |
20 features for scanning and parsing text as well as features for handling | |
21 files, buffers, displays, subprocesses, and so on. Emacs Lisp is | |
22 closely integrated with the editing facilities; thus, editing commands | |
23 are functions that can also conveniently be called from Lisp programs, | |
24 and parameters for customization are ordinary Lisp variables. | |
25 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
26 This manual attempts to be a full description of Emacs Lisp. For a |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
27 beginner's introduction to Emacs Lisp, see @cite{An Introduction to |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
28 Emacs Lisp Programming}, by Bob Chassell, also published by the Free |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
29 Software Foundation. This manual presumes considerable familiarity with |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
30 the use of Emacs for editing; see @cite{The GNU Emacs Manual} for this |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
31 basic information. |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
32 |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
33 Generally speaking, the earlier chapters describe features of Emacs |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
34 Lisp that have counterparts in many programming languages, and later |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
35 chapters describe features that are peculiar to Emacs Lisp or relate |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
36 specifically to editing. |
6453 | 37 |
63213
aec5bc9f2868
Don't set VERSION here a second time. Mention Emacs' version too.
Lute Kamstra <lute@gnu.org>
parents:
58497
diff
changeset
|
38 This is edition @value{VERSION} of the GNU Emacs Lisp Reference |
aec5bc9f2868
Don't set VERSION here a second time. Mention Emacs' version too.
Lute Kamstra <lute@gnu.org>
parents:
58497
diff
changeset
|
39 Manual, corresponding to Emacs version @value{EMACSVER}. |
6453 | 40 |
41 @menu | |
42 * Caveats:: Flaws and a request for help. | |
43 * Lisp History:: Emacs Lisp is descended from Maclisp. | |
44 * Conventions:: How the manual is formatted. | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
45 * Version Info:: Which Emacs version is running? |
6453 | 46 * Acknowledgements:: The authors, editors, and sponsors of this manual. |
47 @end menu | |
48 | |
49 @node Caveats | |
50 @section Caveats | |
40470 | 51 @cindex bugs in this manual |
6453 | 52 |
53 This manual has gone through numerous drafts. It is nearly complete | |
7114 | 54 but not flawless. There are a few topics that are not covered, either |
55 because we consider them secondary (such as most of the individual | |
56 modes) or because they are yet to be written. Because we are not able | |
57 to deal with them completely, we have left out several parts | |
58 intentionally. This includes most information about usage on VMS. | |
6453 | 59 |
60 The manual should be fully correct in what it does cover, and it is | |
61 therefore open to criticism on anything it says---from specific examples | |
62 and descriptive text, to the ordering of chapters and sections. If | |
63 something is confusing, or you find that you have to look at the sources | |
64 or experiment to learn something not covered in the manual, then perhaps | |
65 the manual should be fixed. Please let us know. | |
66 | |
67 @iftex | |
25875 | 68 As you use this manual, we ask that you mark pages with corrections so |
69 you can later look them up and send them to us. If you think of a simple, | |
7114 | 70 real-life example for a function or group of functions, please make an |
6453 | 71 effort to write it up and send it in. Please reference any comments to |
72 the chapter name, section name, and function name, as appropriate, since | |
7114 | 73 page numbers and chapter and section numbers will change and we may have |
74 trouble finding the text you are talking about. Also state the number | |
75 of the edition you are criticizing. | |
6453 | 76 @end iftex |
27193 | 77 @ifnottex |
6453 | 78 |
79 As you use this manual, we ask that you send corrections as soon as you | |
80 find them. If you think of a simple, real life example for a function | |
81 or group of functions, please make an effort to write it up and send it | |
82 in. Please reference any comments to the node name and function or | |
83 variable name, as appropriate. Also state the number of the edition | |
25875 | 84 you are criticizing. |
27193 | 85 @end ifnottex |
6453 | 86 |
48019 | 87 @cindex bugs |
88 @cindex suggestions | |
6453 | 89 Please mail comments and corrections to |
90 | |
91 @example | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
92 bug-lisp-manual@@gnu.org |
6453 | 93 @end example |
94 | |
95 @noindent | |
96 We let mail to this list accumulate unread until someone decides to | |
97 apply the corrections. Months, and sometimes years, go by between | |
98 updates. So please attach no significance to the lack of a reply---your | |
99 mail @emph{will} be acted on in due time. If you want to contact the | |
100 Emacs maintainers more quickly, send mail to | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
101 @code{bug-gnu-emacs@@gnu.org}. |
6453 | 102 |
103 @node Lisp History | |
104 @section Lisp History | |
105 @cindex Lisp history | |
106 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
107 Lisp (LISt Processing language) was first developed in the late 1950s |
6453 | 108 at the Massachusetts Institute of Technology for research in artificial |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
109 intelligence. The great power of the Lisp language makes it ideal |
6453 | 110 for other purposes as well, such as writing editing commands. |
111 | |
112 @cindex Maclisp | |
113 @cindex Common Lisp | |
114 Dozens of Lisp implementations have been built over the years, each | |
115 with its own idiosyncrasies. Many of them were inspired by Maclisp, | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
116 which was written in the 1960s at MIT's Project MAC. Eventually the |
7114 | 117 implementors of the descendants of Maclisp came together and developed a |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
118 standard for Lisp systems, called Common Lisp. In the meantime, Gerry |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
119 Sussman and Guy Steele at MIT developed a simplified but very powerful |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
120 dialect of Lisp, called Scheme. |
6453 | 121 |
122 GNU Emacs Lisp is largely inspired by Maclisp, and a little by Common | |
123 Lisp. If you know Common Lisp, you will notice many similarities. | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
124 However, many features of Common Lisp have been omitted or |
6453 | 125 simplified in order to reduce the memory requirements of GNU Emacs. |
126 Sometimes the simplifications are so drastic that a Common Lisp user | |
127 might be very confused. We will occasionally point out how GNU Emacs | |
128 Lisp differs from Common Lisp. If you don't know Common Lisp, don't | |
129 worry about it; this manual is self-contained. | |
130 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
131 @pindex cl |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
132 A certain amount of Common Lisp emulation is available via the |
54394
897eca9a17ed
(Lisp History): Replace xref to `cl' manual with inforef.
Luc Teirlinck <teirllm@auburn.edu>
parents:
54377
diff
changeset
|
133 @file{cl} library. @inforef{Top, Overview, cl}. |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
134 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
135 Emacs Lisp is not at all influenced by Scheme; but the GNU project has |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
136 an implementation of Scheme, called Guile. We use Guile in all new GNU |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
137 software that calls for extensibility. |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
138 |
6453 | 139 @node Conventions |
140 @section Conventions | |
141 | |
142 This section explains the notational conventions that are used in this | |
143 manual. You may want to skip this section and refer back to it later. | |
144 | |
145 @menu | |
146 * Some Terms:: Explanation of terms we use in this manual. | |
147 * nil and t:: How the symbols @code{nil} and @code{t} are used. | |
148 * Evaluation Notation:: The format we use for examples of evaluation. | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
149 * Printing Notation:: The format we use when examples print text. |
6453 | 150 * Error Messages:: The format we use for examples of errors. |
151 * Buffer Text Notation:: The format we use for buffer contents in examples. | |
152 * Format of Descriptions:: Notation for describing functions, variables, etc. | |
153 @end menu | |
154 | |
155 @node Some Terms | |
156 @subsection Some Terms | |
157 | |
158 Throughout this manual, the phrases ``the Lisp reader'' and ``the Lisp | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
159 printer'' refer to those routines in Lisp that convert textual |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
160 representations of Lisp objects into actual Lisp objects, and vice |
6453 | 161 versa. @xref{Printed Representation}, for more details. You, the |
162 person reading this manual, are thought of as ``the programmer'' and are | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
163 addressed as ``you''. ``The user'' is the person who uses Lisp |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
164 programs, including those you write. |
6453 | 165 |
166 @cindex fonts | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22366
diff
changeset
|
167 Examples of Lisp code are formatted like this: @code{(list 1 2 3)}. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22366
diff
changeset
|
168 Names that represent metasyntactic variables, or arguments to a function |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22366
diff
changeset
|
169 being described, are formatted like this: @var{first-number}. |
6453 | 170 |
171 @node nil and t | |
172 @subsection @code{nil} and @code{t} | |
173 @cindex @code{nil}, uses of | |
174 @cindex truth value | |
175 @cindex boolean | |
176 @cindex false | |
177 | |
12098 | 178 In Lisp, the symbol @code{nil} has three separate meanings: it |
6453 | 179 is a symbol with the name @samp{nil}; it is the logical truth value |
180 @var{false}; and it is the empty list---the list of zero elements. | |
181 When used as a variable, @code{nil} always has the value @code{nil}. | |
182 | |
183 As far as the Lisp reader is concerned, @samp{()} and @samp{nil} are | |
184 identical: they stand for the same object, the symbol @code{nil}. The | |
185 different ways of writing the symbol are intended entirely for human | |
186 readers. After the Lisp reader has read either @samp{()} or @samp{nil}, | |
187 there is no way to determine which representation was actually written | |
188 by the programmer. | |
189 | |
190 In this manual, we use @code{()} when we wish to emphasize that it | |
191 means the empty list, and we use @code{nil} when we wish to emphasize | |
192 that it means the truth value @var{false}. That is a good convention to use | |
193 in Lisp programs also. | |
194 | |
195 @example | |
196 (cons 'foo ()) ; @r{Emphasize the empty list} | |
197 (not nil) ; @r{Emphasize the truth value @var{false}} | |
198 @end example | |
199 | |
65328
5e93eb177fdb
(nil and t): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents:
64889
diff
changeset
|
200 @cindex @code{t}, uses of |
6453 | 201 @cindex true |
202 In contexts where a truth value is expected, any non-@code{nil} value | |
203 is considered to be @var{true}. However, @code{t} is the preferred way | |
204 to represent the truth value @var{true}. When you need to choose a | |
205 value which represents @var{true}, and there is no other basis for | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
206 choosing, use @code{t}. The symbol @code{t} always has the value |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
207 @code{t}. |
6453 | 208 |
209 In Emacs Lisp, @code{nil} and @code{t} are special symbols that always | |
210 evaluate to themselves. This is so that you do not need to quote them | |
211 to use them as constants in a program. An attempt to change their | |
65328
5e93eb177fdb
(nil and t): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents:
64889
diff
changeset
|
212 values results in a @code{setting-constant} error. @xref{Constant |
6453 | 213 Variables}. |
214 | |
215 @node Evaluation Notation | |
216 @subsection Evaluation Notation | |
217 @cindex evaluation notation | |
218 @cindex documentation notation | |
65328
5e93eb177fdb
(nil and t): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents:
64889
diff
changeset
|
219 @cindex notation |
6453 | 220 |
221 A Lisp expression that you can evaluate is called a @dfn{form}. | |
222 Evaluating a form always produces a result, which is a Lisp object. In | |
223 the examples in this manual, this is indicated with @samp{@result{}}: | |
224 | |
225 @example | |
226 (car '(1 2)) | |
227 @result{} 1 | |
228 @end example | |
229 | |
230 @noindent | |
231 You can read this as ``@code{(car '(1 2))} evaluates to 1''. | |
232 | |
233 When a form is a macro call, it expands into a new form for Lisp to | |
234 evaluate. We show the result of the expansion with | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
235 @samp{@expansion{}}. We may or may not show the result of the |
6453 | 236 evaluation of the expanded form. |
237 | |
238 @example | |
239 (third '(a b c)) | |
240 @expansion{} (car (cdr (cdr '(a b c)))) | |
241 @result{} c | |
242 @end example | |
243 | |
7114 | 244 Sometimes to help describe one form we show another form that |
6453 | 245 produces identical results. The exact equivalence of two forms is |
246 indicated with @samp{@equiv{}}. | |
247 | |
248 @example | |
249 (make-sparse-keymap) @equiv{} (list 'keymap) | |
250 @end example | |
251 | |
252 @node Printing Notation | |
253 @subsection Printing Notation | |
254 @cindex printing notation | |
255 | |
256 Many of the examples in this manual print text when they are | |
7114 | 257 evaluated. If you execute example code in a Lisp Interaction buffer |
258 (such as the buffer @samp{*scratch*}), the printed text is inserted into | |
259 the buffer. If you execute the example by other means (such as by | |
260 evaluating the function @code{eval-region}), the printed text is | |
26288 | 261 displayed in the echo area. |
6453 | 262 |
263 Examples in this manual indicate printed text with @samp{@print{}}, | |
58384
3171059923a2
(Printing Notation): Avoid confusion of `print' when explaining @print.
Richard M. Stallman <rms@gnu.org>
parents:
54394
diff
changeset
|
264 irrespective of where that text goes. The value returned by |
3171059923a2
(Printing Notation): Avoid confusion of `print' when explaining @print.
Richard M. Stallman <rms@gnu.org>
parents:
54394
diff
changeset
|
265 evaluating the form (here @code{bar}) follows on a separate line with |
3171059923a2
(Printing Notation): Avoid confusion of `print' when explaining @print.
Richard M. Stallman <rms@gnu.org>
parents:
54394
diff
changeset
|
266 @samp{@result{}}. |
6453 | 267 |
268 @example | |
269 @group | |
58497
39adaa8660ab
(Printing Notation): Fix previous change.
Richard M. Stallman <rms@gnu.org>
parents:
58384
diff
changeset
|
270 (progn (prin1 'foo) (princ "\n") (prin1 'bar)) |
6453 | 271 @print{} foo |
272 @print{} bar | |
273 @result{} bar | |
274 @end group | |
275 @end example | |
276 | |
277 @node Error Messages | |
278 @subsection Error Messages | |
279 @cindex error message notation | |
280 | |
281 Some examples signal errors. This normally displays an error message | |
282 in the echo area. We show the error message on a line starting with | |
283 @samp{@error{}}. Note that @samp{@error{}} itself does not appear in | |
284 the echo area. | |
285 | |
286 @example | |
287 (+ 23 'x) | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
288 @error{} Wrong type argument: number-or-marker-p, x |
6453 | 289 @end example |
290 | |
291 @node Buffer Text Notation | |
292 @subsection Buffer Text Notation | |
293 @cindex buffer text notation | |
294 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22366
diff
changeset
|
295 Some examples describe modifications to the contents of a buffer, by |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22366
diff
changeset
|
296 showing the ``before'' and ``after'' versions of the text. These |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22366
diff
changeset
|
297 examples show the contents of the buffer in question between two lines |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22366
diff
changeset
|
298 of dashes containing the buffer name. In addition, @samp{@point{}} |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22366
diff
changeset
|
299 indicates the location of point. (The symbol for point, of course, is |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22366
diff
changeset
|
300 not part of the text in the buffer; it indicates the place |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22366
diff
changeset
|
301 @emph{between} two characters where point is currently located.) |
6453 | 302 |
303 @example | |
304 ---------- Buffer: foo ---------- | |
305 This is the @point{}contents of foo. | |
306 ---------- Buffer: foo ---------- | |
307 | |
308 (insert "changed ") | |
309 @result{} nil | |
310 ---------- Buffer: foo ---------- | |
311 This is the changed @point{}contents of foo. | |
312 ---------- Buffer: foo ---------- | |
313 @end example | |
314 | |
315 @node Format of Descriptions | |
316 @subsection Format of Descriptions | |
317 @cindex description format | |
318 | |
319 Functions, variables, macros, commands, user options, and special | |
320 forms are described in this manual in a uniform format. The first | |
321 line of a description contains the name of the item followed by its | |
322 arguments, if any. | |
27193 | 323 @ifnottex |
6453 | 324 The category---function, variable, or whatever---appears at the |
325 beginning of the line. | |
27193 | 326 @end ifnottex |
6453 | 327 @iftex |
328 The category---function, variable, or whatever---is printed next to the | |
329 right margin. | |
330 @end iftex | |
331 The description follows on succeeding lines, sometimes with examples. | |
332 | |
333 @menu | |
334 * A Sample Function Description:: A description of an imaginary | |
335 function, @code{foo}. | |
336 * A Sample Variable Description:: A description of an imaginary | |
337 variable, | |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
48019
diff
changeset
|
338 @code{electric-future-map}. |
6453 | 339 @end menu |
340 | |
341 @node A Sample Function Description | |
342 @subsubsection A Sample Function Description | |
343 @cindex function descriptions | |
344 @cindex command descriptions | |
345 @cindex macro descriptions | |
346 @cindex special form descriptions | |
347 | |
348 In a function description, the name of the function being described | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
349 appears first. It is followed on the same line by a list of argument |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
350 names. These names are also used in the body of the description, to |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
351 stand for the values of the arguments. |
6453 | 352 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
353 The appearance of the keyword @code{&optional} in the argument list |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
354 indicates that the subsequent arguments may be omitted (omitted |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
355 arguments default to @code{nil}). Do not write @code{&optional} when |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
356 you call the function. |
6453 | 357 |
65328
5e93eb177fdb
(nil and t): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents:
64889
diff
changeset
|
358 The keyword @code{&rest} (which must be followed by a single |
5e93eb177fdb
(nil and t): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents:
64889
diff
changeset
|
359 argument name) indicates that any number of arguments can follow. The |
5e93eb177fdb
(nil and t): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents:
64889
diff
changeset
|
360 single argument name following @code{&rest} will receive, as its |
5e93eb177fdb
(nil and t): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents:
64889
diff
changeset
|
361 value, a list of all the remaining arguments passed to the function. |
5e93eb177fdb
(nil and t): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents:
64889
diff
changeset
|
362 Do not write @code{&rest} when you call the function. |
6453 | 363 |
364 Here is a description of an imaginary function @code{foo}: | |
365 | |
366 @defun foo integer1 &optional integer2 &rest integers | |
367 The function @code{foo} subtracts @var{integer1} from @var{integer2}, | |
368 then adds all the rest of the arguments to the result. If @var{integer2} | |
369 is not supplied, then the number 19 is used by default. | |
370 | |
371 @example | |
372 (foo 1 5 3 9) | |
373 @result{} 16 | |
374 (foo 5) | |
375 @result{} 14 | |
376 @end example | |
377 | |
22274
f0cd03a7dac9
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
378 @need 1500 |
6453 | 379 More generally, |
380 | |
381 @example | |
382 (foo @var{w} @var{x} @var{y}@dots{}) | |
383 @equiv{} | |
384 (+ (- @var{x} @var{w}) @var{y}@dots{}) | |
385 @end example | |
386 @end defun | |
387 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
388 Any argument whose name contains the name of a type (e.g., |
6453 | 389 @var{integer}, @var{integer1} or @var{buffer}) is expected to be of that |
390 type. A plural of a type (such as @var{buffers}) often means a list of | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
391 objects of that type. Arguments named @var{object} may be of any type. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
392 (@xref{Lisp Data Types}, for a list of Emacs object types.) Arguments |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
393 with other sorts of names (e.g., @var{new-file}) are discussed |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
394 specifically in the description of the function. In some sections, |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
395 features common to the arguments of several functions are described at |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
396 the beginning. |
6453 | 397 |
398 @xref{Lambda Expressions}, for a more complete description of optional | |
399 and rest arguments. | |
400 | |
401 Command, macro, and special form descriptions have the same format, | |
402 but the word `Function' is replaced by `Command', `Macro', or `Special | |
403 Form', respectively. Commands are simply functions that may be called | |
404 interactively; macros process their arguments differently from functions | |
405 (the arguments are not evaluated), but are presented the same way. | |
406 | |
407 Special form descriptions use a more complex notation to specify | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
408 optional and repeated arguments because they can break the argument |
6453 | 409 list down into separate arguments in more complicated ways. |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
410 @samp{@r{[}@var{optional-arg}@r{]}} means that @var{optional-arg} is |
6453 | 411 optional and @samp{@var{repeated-args}@dots{}} stands for zero or more |
412 arguments. Parentheses are used when several arguments are grouped into | |
413 additional levels of list structure. Here is an example: | |
414 | |
415 @defspec count-loop (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{} | |
416 This imaginary special form implements a loop that executes the | |
417 @var{body} forms and then increments the variable @var{var} on each | |
418 iteration. On the first iteration, the variable has the value | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
419 @var{from}; on subsequent iterations, it is incremented by one (or by |
6453 | 420 @var{inc} if that is given). The loop exits before executing @var{body} |
421 if @var{var} equals @var{to}. Here is an example: | |
422 | |
423 @example | |
424 (count-loop (i 0 10) | |
425 (prin1 i) (princ " ") | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
426 (prin1 (aref vector i)) |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
427 (terpri)) |
6453 | 428 @end example |
429 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
430 If @var{from} and @var{to} are omitted, @var{var} is bound to |
6453 | 431 @code{nil} before the loop begins, and the loop exits if @var{var} is |
432 non-@code{nil} at the beginning of an iteration. Here is an example: | |
433 | |
434 @example | |
435 (count-loop (done) | |
436 (if (pending) | |
437 (fixit) | |
438 (setq done t))) | |
439 @end example | |
440 | |
441 In this special form, the arguments @var{from} and @var{to} are | |
442 optional, but must both be present or both absent. If they are present, | |
443 @var{inc} may optionally be specified as well. These arguments are | |
444 grouped with the argument @var{var} into a list, to distinguish them | |
445 from @var{body}, which includes all remaining elements of the form. | |
446 @end defspec | |
447 | |
448 @node A Sample Variable Description | |
449 @subsubsection A Sample Variable Description | |
450 @cindex variable descriptions | |
451 @cindex option descriptions | |
452 | |
65328
5e93eb177fdb
(nil and t): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents:
64889
diff
changeset
|
453 A @dfn{variable} is a name that can hold a value. Although nearly |
5e93eb177fdb
(nil and t): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents:
64889
diff
changeset
|
454 all variables can be set by the user, certain variables exist |
5e93eb177fdb
(nil and t): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents:
64889
diff
changeset
|
455 specifically so that users can change them; these are called @dfn{user |
6453 | 456 options}. Ordinary variables and user options are described using a |
457 format like that for functions except that there are no arguments. | |
458 | |
459 Here is a description of the imaginary @code{electric-future-map} | |
460 variable.@refill | |
461 | |
462 @defvar electric-future-map | |
463 The value of this variable is a full keymap used by Electric Command | |
464 Future mode. The functions in this map allow you to edit commands you | |
465 have not yet thought about executing. | |
466 @end defvar | |
467 | |
468 User option descriptions have the same format, but `Variable' is | |
469 replaced by `User Option'. | |
470 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
471 @node Version Info |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
472 @section Version Information |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
473 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
474 These facilities provide information about which version of Emacs is |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
475 in use. |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
476 |
54377
a9843a971cfc
(Version Info): Add arg to emacs-version.
Richard M. Stallman <rms@gnu.org>
parents:
52401
diff
changeset
|
477 @deffn Command emacs-version &optional here |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
478 This function returns a string describing the version of Emacs that is |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
479 running. It is useful to include this string in bug reports. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
480 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
481 @smallexample |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
482 @group |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
483 (emacs-version) |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
484 @result{} "GNU Emacs 20.3.5 (i486-pc-linux-gnulibc1, X toolkit) |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
485 of Sat Feb 14 1998 on psilocin.gnu.org" |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
486 @end group |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
487 @end smallexample |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
488 |
54377
a9843a971cfc
(Version Info): Add arg to emacs-version.
Richard M. Stallman <rms@gnu.org>
parents:
52401
diff
changeset
|
489 If @var{here} is non-@code{nil}, it inserts the text in the buffer |
a9843a971cfc
(Version Info): Add arg to emacs-version.
Richard M. Stallman <rms@gnu.org>
parents:
52401
diff
changeset
|
490 before point, and returns @code{nil}. Called interactively, the |
a9843a971cfc
(Version Info): Add arg to emacs-version.
Richard M. Stallman <rms@gnu.org>
parents:
52401
diff
changeset
|
491 function prints the same information in the echo area, but giving a |
a9843a971cfc
(Version Info): Add arg to emacs-version.
Richard M. Stallman <rms@gnu.org>
parents:
52401
diff
changeset
|
492 prefix argument makes @var{here} non-@code{nil}. |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
493 @end deffn |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
494 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
495 @defvar emacs-build-time |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
496 The value of this variable indicates the time at which Emacs was built |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
497 at the local site. It is a list of three integers, like the value |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
498 of @code{current-time} (@pxref{Time of Day}). |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
499 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
500 @example |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
501 @group |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
502 emacs-build-time |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
503 @result{} (13623 62065 344633) |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
504 @end group |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
505 @end example |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
506 @end defvar |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
507 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
508 @defvar emacs-version |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
509 The value of this variable is the version of Emacs being run. It is a |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
510 string such as @code{"20.3.1"}. The last number in this string is not |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
511 really part of the Emacs release version number; it is incremented each |
36986 | 512 time you build Emacs in any given directory. A value with four numeric |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22366
diff
changeset
|
513 components, such as @code{"20.3.9.1"}, indicates an unreleased test |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22366
diff
changeset
|
514 version. |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
515 @end defvar |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
516 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
517 The following two variables have existed since Emacs version 19.23: |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
518 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
519 @defvar emacs-major-version |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
520 The major version number of Emacs, as an integer. For Emacs version |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
521 20.3, the value is 20. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
522 @end defvar |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
523 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
524 @defvar emacs-minor-version |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
525 The minor version number of Emacs, as an integer. For Emacs version |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
526 20.3, the value is 3. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
527 @end defvar |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
528 |
6453 | 529 @node Acknowledgements |
530 @section Acknowledgements | |
531 | |
532 This manual was written by Robert Krawitz, Bil Lewis, Dan LaLiberte, | |
533 Richard M. Stallman and Chris Welty, the volunteers of the GNU manual | |
534 group, in an effort extending over several years. Robert J. Chassell | |
535 helped to review and edit the manual, with the support of the Defense | |
536 Advanced Research Projects Agency, ARPA Order 6082, arranged by Warren | |
25875 | 537 A. Hunt, Jr.@: of Computational Logic, Inc. |
6453 | 538 |
539 Corrections were supplied by Karl Berry, Jim Blandy, Bard Bloom, | |
540 Stephane Boucher, David Boyes, Alan Carroll, Richard Davis, Lawrence | |
541 R. Dodd, Peter Doornbosch, David A. Duff, Chris Eich, Beverly | |
542 Erlebacher, David Eckelkamp, Ralf Fassel, Eirik Fuller, Stephen Gildea, | |
543 Bob Glickstein, Eric Hanchrow, George Hartzell, Nathan Hess, Masayuki | |
544 Ida, Dan Jacobson, Jak Kirman, Bob Knighten, Frederick M. Korz, Joe | |
545 Lammens, Glenn M. Lewis, K. Richard Magill, Brian Marick, Roland | |
546 McGrath, Skip Montanaro, John Gardiner Myers, Thomas A. Peterson, | |
547 Francesco Potorti, Friedrich Pukelsheim, Arnold D. Robbins, Raul | |
25875 | 548 Rockwell, Per Starb@"ack, Shinichirou Sugou, Kimmo Suominen, Edward Tharp, |
6453 | 549 Bill Trost, Rickard Westman, Jean White, Matthew Wilding, Carl Witty, |
550 Dale Worley, Rusty Wright, and David D. Zuhn. | |
52401 | 551 |
552 @ignore | |
553 arch-tag: d156593f-82f8-4708-a844-204e48f7f2aa | |
554 @end ignore |