Commit | Line | Data |
---|---|---|
83ac6b45 RS |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Emacs Lisp Reference Manual. | |
3 | @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. | |
4 | @c See the file elisp.texi for copying conditions. | |
5 | @setfilename ../info/intro | |
6 | ||
7 | @node Copying, Introduction, Top, Top | |
8 | @comment node-name, next, previous, up | |
9 | @unnumbered GNU GENERAL PUBLIC LICENSE | |
10 | @center Version 2, June 1991 | |
11 | ||
12 | @display | |
13 | Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc. | |
bda144f4 | 14 | 675 Mass Ave, Cambridge, MA 02139, USA |
83ac6b45 RS |
15 | |
16 | Everyone is permitted to copy and distribute verbatim copies | |
17 | of this license document, but changing it is not allowed. | |
18 | @end display | |
19 | ||
20 | @unnumberedsec Preamble | |
21 | ||
22 | The licenses for most software are designed to take away your | |
23 | freedom to share and change it. By contrast, the GNU General Public | |
24 | License is intended to guarantee your freedom to share and change free | |
25 | software---to make sure the software is free for all its users. This | |
26 | General Public License applies to most of the Free Software | |
27 | Foundation's software and to any other program whose authors commit to | |
28 | using it. (Some other Free Software Foundation software is covered by | |
29 | the GNU Library General Public License instead.) You can apply it to | |
30 | your programs, too. | |
31 | ||
32 | When we speak of free software, we are referring to freedom, not | |
33 | price. Our General Public Licenses are designed to make sure that you | |
34 | have the freedom to distribute copies of free software (and charge for | |
35 | this service if you wish), that you receive source code or can get it | |
36 | if you want it, that you can change the software or use pieces of it | |
37 | in new free programs; and that you know you can do these things. | |
38 | ||
39 | To protect your rights, we need to make restrictions that forbid | |
40 | anyone to deny you these rights or to ask you to surrender the rights. | |
41 | These restrictions translate to certain responsibilities for you if you | |
42 | distribute copies of the software, or if you modify it. | |
43 | ||
44 | For example, if you distribute copies of such a program, whether | |
45 | gratis or for a fee, you must give the recipients all the rights that | |
46 | you have. You must make sure that they, too, receive or can get the | |
47 | source code. And you must show them these terms so they know their | |
48 | rights. | |
49 | ||
50 | We protect your rights with two steps: (1) copyright the software, and | |
51 | (2) offer you this license which gives you legal permission to copy, | |
52 | distribute and/or modify the software. | |
53 | ||
54 | Also, for each author's protection and ours, we want to make certain | |
55 | that everyone understands that there is no warranty for this free | |
56 | software. If the software is modified by someone else and passed on, we | |
57 | want its recipients to know that what they have is not the original, so | |
58 | that any problems introduced by others will not reflect on the original | |
59 | authors' reputations. | |
60 | ||
61 | Finally, any free program is threatened constantly by software | |
62 | patents. We wish to avoid the danger that redistributors of a free | |
63 | program will individually obtain patent licenses, in effect making the | |
64 | program proprietary. To prevent this, we have made it clear that any | |
65 | patent must be licensed for everyone's free use or not licensed at all. | |
66 | ||
67 | The precise terms and conditions for copying, distribution and | |
68 | modification follow. | |
69 | ||
70 | @iftex | |
71 | @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION | |
72 | @end iftex | |
73 | @ifinfo | |
74 | @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION | |
75 | @end ifinfo | |
76 | ||
77 | @enumerate 0 | |
78 | @item | |
79 | This License applies to any program or other work which contains | |
80 | a notice placed by the copyright holder saying it may be distributed | |
81 | under the terms of this General Public License. The ``Program'', below, | |
82 | refers to any such program or work, and a ``work based on the Program'' | |
83 | means either the Program or any derivative work under copyright law: | |
84 | that is to say, a work containing the Program or a portion of it, | |
85 | either verbatim or with modifications and/or translated into another | |
86 | language. (Hereinafter, translation is included without limitation in | |
87 | the term ``modification''.) Each licensee is addressed as ``you''. | |
88 | ||
89 | Activities other than copying, distribution and modification are not | |
90 | covered by this License; they are outside its scope. The act of | |
91 | running the Program is not restricted, and the output from the Program | |
92 | is covered only if its contents constitute a work based on the | |
93 | Program (independent of having been made by running the Program). | |
94 | Whether that is true depends on what the Program does. | |
95 | ||
96 | @item | |
97 | You may copy and distribute verbatim copies of the Program's | |
98 | source code as you receive it, in any medium, provided that you | |
99 | conspicuously and appropriately publish on each copy an appropriate | |
100 | copyright notice and disclaimer of warranty; keep intact all the | |
101 | notices that refer to this License and to the absence of any warranty; | |
102 | and give any other recipients of the Program a copy of this License | |
103 | along with the Program. | |
104 | ||
105 | You may charge a fee for the physical act of transferring a copy, and | |
106 | you may at your option offer warranty protection in exchange for a fee. | |
107 | ||
108 | @item | |
109 | You may modify your copy or copies of the Program or any portion | |
110 | of it, thus forming a work based on the Program, and copy and | |
111 | distribute such modifications or work under the terms of Section 1 | |
112 | above, provided that you also meet all of these conditions: | |
113 | ||
114 | @enumerate a | |
115 | @item | |
116 | You must cause the modified files to carry prominent notices | |
117 | stating that you changed the files and the date of any change. | |
118 | ||
119 | @item | |
120 | You must cause any work that you distribute or publish, that in | |
121 | whole or in part contains or is derived from the Program or any | |
122 | part thereof, to be licensed as a whole at no charge to all third | |
123 | parties under the terms of this License. | |
124 | ||
125 | @item | |
126 | If the modified program normally reads commands interactively | |
127 | when run, you must cause it, when started running for such | |
128 | interactive use in the most ordinary way, to print or display an | |
129 | announcement including an appropriate copyright notice and a | |
130 | notice that there is no warranty (or else, saying that you provide | |
131 | a warranty) and that users may redistribute the program under | |
132 | these conditions, and telling the user how to view a copy of this | |
133 | License. (Exception: if the Program itself is interactive but | |
134 | does not normally print such an announcement, your work based on | |
135 | the Program is not required to print an announcement.) | |
136 | @end enumerate | |
137 | ||
138 | These requirements apply to the modified work as a whole. If | |
139 | identifiable sections of that work are not derived from the Program, | |
140 | and can be reasonably considered independent and separate works in | |
141 | themselves, then this License, and its terms, do not apply to those | |
142 | sections when you distribute them as separate works. But when you | |
143 | distribute the same sections as part of a whole which is a work based | |
144 | on the Program, the distribution of the whole must be on the terms of | |
145 | this License, whose permissions for other licensees extend to the | |
146 | entire whole, and thus to each and every part regardless of who wrote it. | |
147 | ||
148 | Thus, it is not the intent of this section to claim rights or contest | |
149 | your rights to work written entirely by you; rather, the intent is to | |
150 | exercise the right to control the distribution of derivative or | |
151 | collective works based on the Program. | |
152 | ||
153 | In addition, mere aggregation of another work not based on the Program | |
154 | with the Program (or with a work based on the Program) on a volume of | |
155 | a storage or distribution medium does not bring the other work under | |
156 | the scope of this License. | |
157 | ||
158 | @item | |
159 | You may copy and distribute the Program (or a work based on it, | |
160 | under Section 2) in object code or executable form under the terms of | |
161 | Sections 1 and 2 above provided that you also do one of the following: | |
162 | ||
163 | @enumerate a | |
164 | @item | |
165 | Accompany it with the complete corresponding machine-readable | |
166 | source code, which must be distributed under the terms of Sections | |
167 | 1 and 2 above on a medium customarily used for software interchange; or, | |
168 | ||
169 | @item | |
170 | Accompany it with a written offer, valid for at least three | |
171 | years, to give any third party, for a charge no more than your | |
172 | cost of physically performing source distribution, a complete | |
173 | machine-readable copy of the corresponding source code, to be | |
174 | distributed under the terms of Sections 1 and 2 above on a medium | |
175 | customarily used for software interchange; or, | |
176 | ||
177 | @item | |
178 | Accompany it with the information you received as to the offer | |
179 | to distribute corresponding source code. (This alternative is | |
180 | allowed only for noncommercial distribution and only if you | |
181 | received the program in object code or executable form with such | |
182 | an offer, in accord with Subsection b above.) | |
183 | @end enumerate | |
184 | ||
185 | The source code for a work means the preferred form of the work for | |
186 | making modifications to it. For an executable work, complete source | |
187 | code means all the source code for all modules it contains, plus any | |
188 | associated interface definition files, plus the scripts used to | |
189 | control compilation and installation of the executable. However, as a | |
190 | special exception, the source code distributed need not include | |
191 | anything that is normally distributed (in either source or binary | |
192 | form) with the major components (compiler, kernel, and so on) of the | |
193 | operating system on which the executable runs, unless that component | |
194 | itself accompanies the executable. | |
195 | ||
196 | If distribution of executable or object code is made by offering | |
197 | access to copy from a designated place, then offering equivalent | |
198 | access to copy the source code from the same place counts as | |
199 | distribution of the source code, even though third parties are not | |
200 | compelled to copy the source along with the object code. | |
201 | ||
202 | @item | |
203 | You may not copy, modify, sublicense, or distribute the Program | |
204 | except as expressly provided under this License. Any attempt | |
205 | otherwise to copy, modify, sublicense or distribute the Program is | |
206 | void, and will automatically terminate your rights under this License. | |
207 | However, parties who have received copies, or rights, from you under | |
208 | this License will not have their licenses terminated so long as such | |
209 | parties remain in full compliance. | |
210 | ||
211 | @item | |
212 | You are not required to accept this License, since you have not | |
213 | signed it. However, nothing else grants you permission to modify or | |
214 | distribute the Program or its derivative works. These actions are | |
215 | prohibited by law if you do not accept this License. Therefore, by | |
216 | modifying or distributing the Program (or any work based on the | |
217 | Program), you indicate your acceptance of this License to do so, and | |
218 | all its terms and conditions for copying, distributing or modifying | |
219 | the Program or works based on it. | |
220 | ||
221 | @item | |
222 | Each time you redistribute the Program (or any work based on the | |
223 | Program), the recipient automatically receives a license from the | |
224 | original licensor to copy, distribute or modify the Program subject to | |
225 | these terms and conditions. You may not impose any further | |
226 | restrictions on the recipients' exercise of the rights granted herein. | |
227 | You are not responsible for enforcing compliance by third parties to | |
228 | this License. | |
229 | ||
230 | @item | |
231 | If, as a consequence of a court judgment or allegation of patent | |
232 | infringement or for any other reason (not limited to patent issues), | |
233 | conditions are imposed on you (whether by court order, agreement or | |
234 | otherwise) that contradict the conditions of this License, they do not | |
235 | excuse you from the conditions of this License. If you cannot | |
236 | distribute so as to satisfy simultaneously your obligations under this | |
237 | License and any other pertinent obligations, then as a consequence you | |
238 | may not distribute the Program at all. For example, if a patent | |
239 | license would not permit royalty-free redistribution of the Program by | |
240 | all those who receive copies directly or indirectly through you, then | |
241 | the only way you could satisfy both it and this License would be to | |
242 | refrain entirely from distribution of the Program. | |
243 | ||
244 | If any portion of this section is held invalid or unenforceable under | |
245 | any particular circumstance, the balance of the section is intended to | |
246 | apply and the section as a whole is intended to apply in other | |
247 | circumstances. | |
248 | ||
249 | It is not the purpose of this section to induce you to infringe any | |
250 | patents or other property right claims or to contest validity of any | |
251 | such claims; this section has the sole purpose of protecting the | |
252 | integrity of the free software distribution system, which is | |
253 | implemented by public license practices. Many people have made | |
254 | generous contributions to the wide range of software distributed | |
255 | through that system in reliance on consistent application of that | |
256 | system; it is up to the author/donor to decide if he or she is willing | |
257 | to distribute software through any other system and a licensee cannot | |
258 | impose that choice. | |
259 | ||
260 | This section is intended to make thoroughly clear what is believed to | |
261 | be a consequence of the rest of this License. | |
262 | ||
263 | @item | |
264 | If the distribution and/or use of the Program is restricted in | |
265 | certain countries either by patents or by copyrighted interfaces, the | |
266 | original copyright holder who places the Program under this License | |
267 | may add an explicit geographical distribution limitation excluding | |
268 | those countries, so that distribution is permitted only in or among | |
269 | countries not thus excluded. In such case, this License incorporates | |
270 | the limitation as if written in the body of this License. | |
271 | ||
272 | @item | |
273 | The Free Software Foundation may publish revised and/or new versions | |
274 | of the General Public License from time to time. Such new versions will | |
275 | be similar in spirit to the present version, but may differ in detail to | |
276 | address new problems or concerns. | |
277 | ||
278 | Each version is given a distinguishing version number. If the Program | |
279 | specifies a version number of this License which applies to it and ``any | |
280 | later version'', you have the option of following the terms and conditions | |
281 | either of that version or of any later version published by the Free | |
282 | Software Foundation. If the Program does not specify a version number of | |
283 | this License, you may choose any version ever published by the Free Software | |
284 | Foundation. | |
285 | ||
286 | @item | |
287 | If you wish to incorporate parts of the Program into other free | |
288 | programs whose distribution conditions are different, write to the author | |
289 | to ask for permission. For software which is copyrighted by the Free | |
290 | Software Foundation, write to the Free Software Foundation; we sometimes | |
291 | make exceptions for this. Our decision will be guided by the two goals | |
292 | of preserving the free status of all derivatives of our free software and | |
293 | of promoting the sharing and reuse of software generally. | |
294 | ||
295 | @iftex | |
296 | @heading NO WARRANTY | |
297 | @end iftex | |
298 | @ifinfo | |
299 | @center NO WARRANTY | |
300 | @end ifinfo | |
301 | ||
302 | @item | |
303 | BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY | |
304 | FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW@. EXCEPT WHEN | |
305 | OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES | |
306 | PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED | |
307 | OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF | |
308 | MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE@. THE ENTIRE RISK AS | |
309 | TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU@. SHOULD THE | |
310 | PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, | |
311 | REPAIR OR CORRECTION. | |
312 | ||
313 | @item | |
314 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING | |
315 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR | |
316 | REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, | |
317 | INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING | |
318 | OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED | |
319 | TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY | |
320 | YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER | |
321 | PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE | |
322 | POSSIBILITY OF SUCH DAMAGES. | |
323 | @end enumerate | |
324 | ||
325 | @iftex | |
326 | @heading END OF TERMS AND CONDITIONS | |
327 | @end iftex | |
328 | @ifinfo | |
329 | @center END OF TERMS AND CONDITIONS | |
330 | @end ifinfo | |
331 | ||
332 | @page | |
333 | @unnumberedsec How to Apply These Terms to Your New Programs | |
334 | ||
335 | If you develop a new program, and you want it to be of the greatest | |
336 | possible use to the public, the best way to achieve this is to make it | |
337 | free software which everyone can redistribute and change under these terms. | |
338 | ||
339 | To do so, attach the following notices to the program. It is safest | |
340 | to attach them to the start of each source file to most effectively | |
341 | convey the exclusion of warranty; and each file should have at least | |
342 | the ``copyright'' line and a pointer to where the full notice is found. | |
343 | ||
344 | @smallexample | |
345 | @var{one line to give the program's name and an idea of what it does.} | |
346 | Copyright (C) 19@var{yy} @var{name of author} | |
347 | ||
348 | This program is free software; you can redistribute it and/or | |
349 | modify it under the terms of the GNU General Public License | |
350 | as published by the Free Software Foundation; either version 2 | |
351 | of the License, or (at your option) any later version. | |
352 | ||
353 | This program is distributed in the hope that it will be useful, | |
354 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
355 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the | |
356 | GNU General Public License for more details. | |
357 | ||
358 | You should have received a copy of the GNU General Public License | |
359 | along with this program; if not, write to the Free Software | |
bda144f4 | 360 | Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. |
83ac6b45 RS |
361 | @end smallexample |
362 | ||
363 | Also add information on how to contact you by electronic and paper mail. | |
364 | ||
365 | If the program is interactive, make it output a short notice like this | |
366 | when it starts in an interactive mode: | |
367 | ||
368 | @smallexample | |
369 | Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author} | |
370 | Gnomovision comes with ABSOLUTELY NO WARRANTY; for details | |
371 | type `show w'. This is free software, and you are welcome | |
372 | to redistribute it under certain conditions; type `show c' | |
373 | for details. | |
374 | @end smallexample | |
375 | ||
376 | The hypothetical commands @samp{show w} and @samp{show c} should show | |
377 | the appropriate parts of the General Public License. Of course, the | |
378 | commands you use may be called something other than @samp{show w} and | |
379 | @samp{show c}; they could even be mouse-clicks or menu items---whatever | |
380 | suits your program. | |
381 | ||
382 | You should also get your employer (if you work as a programmer) or your | |
383 | school, if any, to sign a ``copyright disclaimer'' for the program, if | |
384 | necessary. Here is a sample; alter the names: | |
385 | ||
386 | @smallexample | |
387 | @group | |
388 | Yoyodyne, Inc., hereby disclaims all copyright | |
389 | interest in the program `Gnomovision' | |
390 | (which makes passes at compilers) written | |
391 | by James Hacker. | |
392 | ||
393 | @var{signature of Ty Coon}, 1 April 1989 | |
394 | Ty Coon, President of Vice | |
395 | @end group | |
396 | @end smallexample | |
397 | ||
398 | This General Public License does not permit incorporating your program into | |
399 | proprietary programs. If your program is a subroutine library, you may | |
400 | consider it more useful to permit linking proprietary applications with the | |
401 | library. If this is what you want to do, use the GNU Library General | |
402 | Public License instead of this License. | |
403 | ||
7791402e | 404 | @node Introduction, Lisp Data Types, Copying, Top |
83ac6b45 RS |
405 | @chapter Introduction |
406 | ||
407 | Most of the GNU Emacs text editor is written in the programming | |
408 | language called Emacs Lisp. You can write new code in Emacs Lisp and | |
409 | install it as an extension to the editor. However, Emacs Lisp is more | |
410 | than a mere ``extension language''; it is a full computer programming | |
411 | language in its own right. You can use it as you would any other | |
412 | programming language. | |
413 | ||
414 | Because Emacs Lisp is designed for use in an editor, it has special | |
415 | features for scanning and parsing text as well as features for handling | |
416 | files, buffers, displays, subprocesses, and so on. Emacs Lisp is | |
417 | closely integrated with the editing facilities; thus, editing commands | |
418 | are functions that can also conveniently be called from Lisp programs, | |
419 | and parameters for customization are ordinary Lisp variables. | |
420 | ||
421 | This manual describes Emacs Lisp, presuming considerable familiarity | |
7791402e | 422 | with the use of Emacs for editing. (See @cite{The GNU Emacs Manual} |
83ac6b45 RS |
423 | for this basic information.) Generally speaking, the earlier chapters |
424 | describe features of Emacs Lisp that have counterparts in many | |
425 | programming languages, and later chapters describe features that are | |
426 | peculiar to Emacs Lisp or relate specifically to editing. | |
427 | ||
bda144f4 | 428 | This is edition 2.4. |
83ac6b45 RS |
429 | |
430 | @menu | |
431 | * Caveats:: Flaws and a request for help. | |
432 | * Lisp History:: Emacs Lisp is descended from Maclisp. | |
433 | * Conventions:: How the manual is formatted. | |
434 | * Acknowledgements:: The authors, editors, and sponsors of this manual. | |
435 | @end menu | |
436 | ||
437 | @node Caveats | |
438 | @section Caveats | |
439 | ||
440 | This manual has gone through numerous drafts. It is nearly complete | |
7791402e RS |
441 | but not flawless. There are a few topics that are not covered, either |
442 | because we consider them secondary (such as most of the individual | |
443 | modes) or because they are yet to be written. Because we are not able | |
444 | to deal with them completely, we have left out several parts | |
445 | intentionally. This includes most information about usage on VMS. | |
83ac6b45 RS |
446 | |
447 | The manual should be fully correct in what it does cover, and it is | |
448 | therefore open to criticism on anything it says---from specific examples | |
449 | and descriptive text, to the ordering of chapters and sections. If | |
450 | something is confusing, or you find that you have to look at the sources | |
451 | or experiment to learn something not covered in the manual, then perhaps | |
452 | the manual should be fixed. Please let us know. | |
453 | ||
454 | @iftex | |
455 | As you use the manual, we ask that you mark pages with corrections so | |
456 | you can later look them up and send them in. If you think of a simple, | |
7791402e | 457 | real-life example for a function or group of functions, please make an |
83ac6b45 RS |
458 | effort to write it up and send it in. Please reference any comments to |
459 | the chapter name, section name, and function name, as appropriate, since | |
7791402e RS |
460 | page numbers and chapter and section numbers will change and we may have |
461 | trouble finding the text you are talking about. Also state the number | |
462 | of the edition you are criticizing. | |
83ac6b45 RS |
463 | @end iftex |
464 | @ifinfo | |
465 | ||
466 | As you use this manual, we ask that you send corrections as soon as you | |
467 | find them. If you think of a simple, real life example for a function | |
468 | or group of functions, please make an effort to write it up and send it | |
469 | in. Please reference any comments to the node name and function or | |
470 | variable name, as appropriate. Also state the number of the edition | |
471 | which you are criticizing. | |
472 | @end ifinfo | |
473 | ||
474 | Please mail comments and corrections to | |
475 | ||
476 | @example | |
477 | bug-lisp-manual@@prep.ai.mit.edu | |
478 | @end example | |
479 | ||
480 | @noindent | |
481 | We let mail to this list accumulate unread until someone decides to | |
482 | apply the corrections. Months, and sometimes years, go by between | |
483 | updates. So please attach no significance to the lack of a reply---your | |
484 | mail @emph{will} be acted on in due time. If you want to contact the | |
485 | Emacs maintainers more quickly, send mail to | |
486 | @code{bug-gnu-emacs@@prep.ai.mit.edu}. | |
487 | ||
488 | @display | |
489 | --Bil Lewis, Dan LaLiberte, Richard Stallman | |
490 | @end display | |
491 | ||
492 | @node Lisp History | |
493 | @section Lisp History | |
494 | @cindex Lisp history | |
495 | ||
7791402e | 496 | Lisp (LISt Processing language) was first developed in the late 1950's |
83ac6b45 RS |
497 | at the Massachusetts Institute of Technology for research in artificial |
498 | intelligence. The great power of the Lisp language makes it superior | |
499 | for other purposes as well, such as writing editing commands. | |
500 | ||
501 | @cindex Maclisp | |
502 | @cindex Common Lisp | |
503 | Dozens of Lisp implementations have been built over the years, each | |
504 | with its own idiosyncrasies. Many of them were inspired by Maclisp, | |
505 | which was written in the 1960's at MIT's Project MAC. Eventually the | |
7791402e | 506 | implementors of the descendants of Maclisp came together and developed a |
83ac6b45 RS |
507 | standard for Lisp systems, called Common Lisp. |
508 | ||
509 | GNU Emacs Lisp is largely inspired by Maclisp, and a little by Common | |
510 | Lisp. If you know Common Lisp, you will notice many similarities. | |
511 | However, many of the features of Common Lisp have been omitted or | |
512 | simplified in order to reduce the memory requirements of GNU Emacs. | |
513 | Sometimes the simplifications are so drastic that a Common Lisp user | |
514 | might be very confused. We will occasionally point out how GNU Emacs | |
515 | Lisp differs from Common Lisp. If you don't know Common Lisp, don't | |
516 | worry about it; this manual is self-contained. | |
517 | ||
518 | @node Conventions | |
519 | @section Conventions | |
520 | ||
521 | This section explains the notational conventions that are used in this | |
522 | manual. You may want to skip this section and refer back to it later. | |
523 | ||
524 | @menu | |
525 | * Some Terms:: Explanation of terms we use in this manual. | |
526 | * nil and t:: How the symbols @code{nil} and @code{t} are used. | |
527 | * Evaluation Notation:: The format we use for examples of evaluation. | |
528 | * Printing Notation:: The format we use for examples that print output. | |
529 | * Error Messages:: The format we use for examples of errors. | |
530 | * Buffer Text Notation:: The format we use for buffer contents in examples. | |
531 | * Format of Descriptions:: Notation for describing functions, variables, etc. | |
532 | @end menu | |
533 | ||
534 | @node Some Terms | |
535 | @subsection Some Terms | |
536 | ||
537 | Throughout this manual, the phrases ``the Lisp reader'' and ``the Lisp | |
538 | printer'' are used to refer to those routines in Lisp that convert | |
bfe721d1 | 539 | textual representations of Lisp objects into actual Lisp objects, and vice |
83ac6b45 RS |
540 | versa. @xref{Printed Representation}, for more details. You, the |
541 | person reading this manual, are thought of as ``the programmer'' and are | |
7791402e | 542 | addressed as ``you''. ``The user'' is the person who uses Lisp programs, |
83ac6b45 RS |
543 | including those you write. |
544 | ||
545 | @cindex fonts | |
546 | Examples of Lisp code appear in this font or form: @code{(list 1 2 | |
547 | 3)}. Names that represent arguments or metasyntactic variables appear | |
548 | in this font or form: @var{first-number}. | |
549 | ||
550 | @node nil and t | |
551 | @subsection @code{nil} and @code{t} | |
552 | @cindex @code{nil}, uses of | |
553 | @cindex truth value | |
554 | @cindex boolean | |
555 | @cindex false | |
556 | ||
bfe721d1 | 557 | In Lisp, the symbol @code{nil} has three separate meanings: it |
83ac6b45 RS |
558 | is a symbol with the name @samp{nil}; it is the logical truth value |
559 | @var{false}; and it is the empty list---the list of zero elements. | |
560 | When used as a variable, @code{nil} always has the value @code{nil}. | |
561 | ||
562 | As far as the Lisp reader is concerned, @samp{()} and @samp{nil} are | |
563 | identical: they stand for the same object, the symbol @code{nil}. The | |
564 | different ways of writing the symbol are intended entirely for human | |
565 | readers. After the Lisp reader has read either @samp{()} or @samp{nil}, | |
566 | there is no way to determine which representation was actually written | |
567 | by the programmer. | |
568 | ||
569 | In this manual, we use @code{()} when we wish to emphasize that it | |
570 | means the empty list, and we use @code{nil} when we wish to emphasize | |
571 | that it means the truth value @var{false}. That is a good convention to use | |
572 | in Lisp programs also. | |
573 | ||
574 | @example | |
575 | (cons 'foo ()) ; @r{Emphasize the empty list} | |
576 | (not nil) ; @r{Emphasize the truth value @var{false}} | |
577 | @end example | |
578 | ||
579 | @cindex @code{t} and truth | |
580 | @cindex true | |
581 | In contexts where a truth value is expected, any non-@code{nil} value | |
582 | is considered to be @var{true}. However, @code{t} is the preferred way | |
583 | to represent the truth value @var{true}. When you need to choose a | |
584 | value which represents @var{true}, and there is no other basis for | |
585 | choosing, use @code{t}. The symbol @code{t} always has value @code{t}. | |
586 | ||
587 | In Emacs Lisp, @code{nil} and @code{t} are special symbols that always | |
588 | evaluate to themselves. This is so that you do not need to quote them | |
589 | to use them as constants in a program. An attempt to change their | |
590 | values results in a @code{setting-constant} error. @xref{Accessing | |
591 | Variables}. | |
592 | ||
593 | @node Evaluation Notation | |
594 | @subsection Evaluation Notation | |
595 | @cindex evaluation notation | |
596 | @cindex documentation notation | |
597 | ||
598 | A Lisp expression that you can evaluate is called a @dfn{form}. | |
599 | Evaluating a form always produces a result, which is a Lisp object. In | |
600 | the examples in this manual, this is indicated with @samp{@result{}}: | |
601 | ||
602 | @example | |
603 | (car '(1 2)) | |
604 | @result{} 1 | |
605 | @end example | |
606 | ||
607 | @noindent | |
608 | You can read this as ``@code{(car '(1 2))} evaluates to 1''. | |
609 | ||
610 | When a form is a macro call, it expands into a new form for Lisp to | |
611 | evaluate. We show the result of the expansion with | |
612 | @samp{@expansion{}}. We may or may not show the actual result of the | |
613 | evaluation of the expanded form. | |
614 | ||
615 | @example | |
616 | (third '(a b c)) | |
617 | @expansion{} (car (cdr (cdr '(a b c)))) | |
618 | @result{} c | |
619 | @end example | |
620 | ||
7791402e | 621 | Sometimes to help describe one form we show another form that |
83ac6b45 RS |
622 | produces identical results. The exact equivalence of two forms is |
623 | indicated with @samp{@equiv{}}. | |
624 | ||
625 | @example | |
626 | (make-sparse-keymap) @equiv{} (list 'keymap) | |
627 | @end example | |
628 | ||
629 | @node Printing Notation | |
630 | @subsection Printing Notation | |
631 | @cindex printing notation | |
632 | ||
633 | Many of the examples in this manual print text when they are | |
7791402e RS |
634 | evaluated. If you execute example code in a Lisp Interaction buffer |
635 | (such as the buffer @samp{*scratch*}), the printed text is inserted into | |
636 | the buffer. If you execute the example by other means (such as by | |
637 | evaluating the function @code{eval-region}), the printed text is | |
638 | displayed in the echo area. You should be aware that text displayed in | |
639 | the echo area is truncated to a single line. | |
83ac6b45 RS |
640 | |
641 | Examples in this manual indicate printed text with @samp{@print{}}, | |
642 | irrespective of where that text goes. The value returned by evaluating | |
643 | the form (here @code{bar}) follows on a separate line. | |
644 | ||
645 | @example | |
646 | @group | |
647 | (progn (print 'foo) (print 'bar)) | |
648 | @print{} foo | |
649 | @print{} bar | |
650 | @result{} bar | |
651 | @end group | |
652 | @end example | |
653 | ||
654 | @node Error Messages | |
655 | @subsection Error Messages | |
656 | @cindex error message notation | |
657 | ||
658 | Some examples signal errors. This normally displays an error message | |
659 | in the echo area. We show the error message on a line starting with | |
660 | @samp{@error{}}. Note that @samp{@error{}} itself does not appear in | |
661 | the echo area. | |
662 | ||
663 | @example | |
664 | (+ 23 'x) | |
665 | @error{} Wrong type argument: integer-or-marker-p, x | |
666 | @end example | |
667 | ||
668 | @node Buffer Text Notation | |
669 | @subsection Buffer Text Notation | |
670 | @cindex buffer text notation | |
671 | ||
672 | Some examples show modifications to text in a buffer, with ``before'' | |
673 | and ``after'' versions of the text. These examples show the contents of | |
674 | the buffer in question between two lines of dashes containing the buffer | |
675 | name. In addition, @samp{@point{}} indicates the location of point. | |
676 | (The symbol for point, of course, is not part of the text in the buffer; | |
677 | it indicates the place @emph{between} two characters where point is | |
678 | located.) | |
679 | ||
680 | @example | |
681 | ---------- Buffer: foo ---------- | |
682 | This is the @point{}contents of foo. | |
683 | ---------- Buffer: foo ---------- | |
684 | ||
685 | (insert "changed ") | |
686 | @result{} nil | |
687 | ---------- Buffer: foo ---------- | |
688 | This is the changed @point{}contents of foo. | |
689 | ---------- Buffer: foo ---------- | |
690 | @end example | |
691 | ||
692 | @node Format of Descriptions | |
693 | @subsection Format of Descriptions | |
694 | @cindex description format | |
695 | ||
696 | Functions, variables, macros, commands, user options, and special | |
697 | forms are described in this manual in a uniform format. The first | |
698 | line of a description contains the name of the item followed by its | |
699 | arguments, if any. | |
700 | @ifinfo | |
701 | The category---function, variable, or whatever---appears at the | |
702 | beginning of the line. | |
703 | @end ifinfo | |
704 | @iftex | |
705 | The category---function, variable, or whatever---is printed next to the | |
706 | right margin. | |
707 | @end iftex | |
708 | The description follows on succeeding lines, sometimes with examples. | |
709 | ||
710 | @menu | |
711 | * A Sample Function Description:: A description of an imaginary | |
712 | function, @code{foo}. | |
713 | * A Sample Variable Description:: A description of an imaginary | |
714 | variable, | |
715 | @code{electric-future-map}. | |
716 | @end menu | |
717 | ||
718 | @node A Sample Function Description | |
719 | @subsubsection A Sample Function Description | |
720 | @cindex function descriptions | |
721 | @cindex command descriptions | |
722 | @cindex macro descriptions | |
723 | @cindex special form descriptions | |
724 | ||
725 | In a function description, the name of the function being described | |
726 | appears first. It is followed on the same line by a list of parameters. | |
727 | The names used for the parameters are also used in the body of the | |
728 | description. | |
729 | ||
730 | The appearance of the keyword @code{&optional} in the parameter list | |
731 | indicates that the arguments for subsequent parameters may be omitted | |
732 | (omitted parameters default to @code{nil}). Do not write | |
733 | @code{&optional} when you call the function. | |
734 | ||
735 | The keyword @code{&rest} (which will always be followed by a single | |
736 | parameter) indicates that any number of arguments can follow. The value | |
737 | of the single following parameter will be a list of all these arguments. | |
738 | Do not write @code{&rest} when you call the function. | |
739 | ||
740 | Here is a description of an imaginary function @code{foo}: | |
741 | ||
742 | @defun foo integer1 &optional integer2 &rest integers | |
743 | The function @code{foo} subtracts @var{integer1} from @var{integer2}, | |
744 | then adds all the rest of the arguments to the result. If @var{integer2} | |
745 | is not supplied, then the number 19 is used by default. | |
746 | ||
747 | @example | |
748 | (foo 1 5 3 9) | |
749 | @result{} 16 | |
750 | (foo 5) | |
751 | @result{} 14 | |
752 | @end example | |
753 | ||
754 | More generally, | |
755 | ||
756 | @example | |
757 | (foo @var{w} @var{x} @var{y}@dots{}) | |
758 | @equiv{} | |
759 | (+ (- @var{x} @var{w}) @var{y}@dots{}) | |
760 | @end example | |
761 | @end defun | |
762 | ||
763 | Any parameter whose name contains the name of a type (e.g., | |
764 | @var{integer}, @var{integer1} or @var{buffer}) is expected to be of that | |
765 | type. A plural of a type (such as @var{buffers}) often means a list of | |
766 | objects of that type. Parameters named @var{object} may be of any type. | |
7791402e | 767 | (@xref{Lisp Data Types}, for a list of Emacs object types.) |
83ac6b45 RS |
768 | Parameters with other sorts of names (e.g., @var{new-file}) are |
769 | discussed specifically in the description of the function. In some | |
770 | sections, features common to parameters of several functions are | |
771 | described at the beginning. | |
772 | ||
773 | @xref{Lambda Expressions}, for a more complete description of optional | |
774 | and rest arguments. | |
775 | ||
776 | Command, macro, and special form descriptions have the same format, | |
777 | but the word `Function' is replaced by `Command', `Macro', or `Special | |
778 | Form', respectively. Commands are simply functions that may be called | |
779 | interactively; macros process their arguments differently from functions | |
780 | (the arguments are not evaluated), but are presented the same way. | |
781 | ||
782 | Special form descriptions use a more complex notation to specify | |
783 | optional and repeated parameters because they can break the argument | |
784 | list down into separate arguments in more complicated ways. | |
785 | @samp{@code{@r{[}@var{optional-arg}@r{]}}} means that @var{optional-arg} is | |
786 | optional and @samp{@var{repeated-args}@dots{}} stands for zero or more | |
787 | arguments. Parentheses are used when several arguments are grouped into | |
788 | additional levels of list structure. Here is an example: | |
789 | ||
790 | @defspec count-loop (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{} | |
791 | This imaginary special form implements a loop that executes the | |
792 | @var{body} forms and then increments the variable @var{var} on each | |
793 | iteration. On the first iteration, the variable has the value | |
794 | @var{from}; on subsequent iterations, it is incremented by 1 (or by | |
795 | @var{inc} if that is given). The loop exits before executing @var{body} | |
796 | if @var{var} equals @var{to}. Here is an example: | |
797 | ||
798 | @example | |
799 | (count-loop (i 0 10) | |
800 | (prin1 i) (princ " ") | |
801 | (prin1 (aref vector i)) (terpri)) | |
802 | @end example | |
803 | ||
804 | If @var{from} and @var{to} are omitted, then @var{var} is bound to | |
805 | @code{nil} before the loop begins, and the loop exits if @var{var} is | |
806 | non-@code{nil} at the beginning of an iteration. Here is an example: | |
807 | ||
808 | @example | |
809 | (count-loop (done) | |
810 | (if (pending) | |
811 | (fixit) | |
812 | (setq done t))) | |
813 | @end example | |
814 | ||
815 | In this special form, the arguments @var{from} and @var{to} are | |
816 | optional, but must both be present or both absent. If they are present, | |
817 | @var{inc} may optionally be specified as well. These arguments are | |
818 | grouped with the argument @var{var} into a list, to distinguish them | |
819 | from @var{body}, which includes all remaining elements of the form. | |
820 | @end defspec | |
821 | ||
822 | @node A Sample Variable Description | |
823 | @subsubsection A Sample Variable Description | |
824 | @cindex variable descriptions | |
825 | @cindex option descriptions | |
826 | ||
827 | A @dfn{variable} is a name that can hold a value. Although any | |
828 | variable can be set by the user, certain variables that exist | |
829 | specifically so that users can change them are called @dfn{user | |
830 | options}. Ordinary variables and user options are described using a | |
831 | format like that for functions except that there are no arguments. | |
832 | ||
833 | Here is a description of the imaginary @code{electric-future-map} | |
834 | variable.@refill | |
835 | ||
836 | @defvar electric-future-map | |
837 | The value of this variable is a full keymap used by Electric Command | |
838 | Future mode. The functions in this map allow you to edit commands you | |
839 | have not yet thought about executing. | |
840 | @end defvar | |
841 | ||
842 | User option descriptions have the same format, but `Variable' is | |
843 | replaced by `User Option'. | |
844 | ||
845 | @node Acknowledgements | |
846 | @section Acknowledgements | |
847 | ||
848 | This manual was written by Robert Krawitz, Bil Lewis, Dan LaLiberte, | |
849 | Richard M. Stallman and Chris Welty, the volunteers of the GNU manual | |
850 | group, in an effort extending over several years. Robert J. Chassell | |
851 | helped to review and edit the manual, with the support of the Defense | |
852 | Advanced Research Projects Agency, ARPA Order 6082, arranged by Warren | |
853 | A. Hunt, Jr. of Computational Logic, Inc. | |
854 | ||
855 | Corrections were supplied by Karl Berry, Jim Blandy, Bard Bloom, | |
856 | Stephane Boucher, David Boyes, Alan Carroll, Richard Davis, Lawrence | |
857 | R. Dodd, Peter Doornbosch, David A. Duff, Chris Eich, Beverly | |
858 | Erlebacher, David Eckelkamp, Ralf Fassel, Eirik Fuller, Stephen Gildea, | |
859 | Bob Glickstein, Eric Hanchrow, George Hartzell, Nathan Hess, Masayuki | |
860 | Ida, Dan Jacobson, Jak Kirman, Bob Knighten, Frederick M. Korz, Joe | |
861 | Lammens, Glenn M. Lewis, K. Richard Magill, Brian Marick, Roland | |
862 | McGrath, Skip Montanaro, John Gardiner Myers, Thomas A. Peterson, | |
863 | Francesco Potorti, Friedrich Pukelsheim, Arnold D. Robbins, Raul | |
864 | Rockwell, Per Starback, Shinichirou Sugou, Kimmo Suominen, Edward Tharp, | |
865 | Bill Trost, Rickard Westman, Jean White, Matthew Wilding, Carl Witty, | |
866 | Dale Worley, Rusty Wright, and David D. Zuhn. |