Mercurial > hg > xemacs-beta

comparison man/lispref/intro.texi @ 0:376386a54a3c r19-14

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