+++ /dev/null
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
-
-INFO-DIR-SECTION XEmacs Editor
-START-INFO-DIR-ENTRY
-* Lispref: (lispref). XEmacs Lisp Reference Manual.
-END-INFO-DIR-ENTRY
-
- Edition History:
-
- GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
-Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
-Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
-XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
-GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
-Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
-Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
-Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
-November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
-
- Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
-Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
-Copyright (C) 1995, 1996 Ben Wing.
-
- Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that this permission notice may be stated in a
-translation approved by the Foundation.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided also
-that the section entitled "GNU General Public License" is included
-exactly as in the original, and provided that the entire resulting
-derived work is distributed under the terms of a permission notice
-identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that the section entitled "GNU General Public License"
-may be included in a translation approved by the Free Software
-Foundation instead of in the original English.
-
-\1f
-File: lispref.info, Node: Copying, Next: Introduction, Prev: Top, Up: Top
-
-GNU GENERAL PUBLIC LICENSE
-**************************
-
- Version 2, June 1991
-
- Copyright (C) 1989, 1991 Free Software Foundation, Inc.
- 675 Mass Ave, Cambridge, MA 02139, USA
-
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
-Preamble
-========
-
- The licenses for most software are designed to take away your
-freedom to share and change it. By contrast, the GNU General Public
-License is intended to guarantee your freedom to share and change free
-software--to make sure the software is free for all its users. This
-General Public License applies to most of the Free Software
-Foundation's software and to any other program whose authors commit to
-using it. (Some other Free Software Foundation software is covered by
-the GNU Library General Public License instead.) You can apply it to
-your programs, too.
-
- When we speak of free software, we are referring to freedom, not
-price. Our General Public Licenses are designed to make sure that you
-have the freedom to distribute copies of free software (and charge for
-this service if you wish), that you receive source code or can get it
-if you want it, that you can change the software or use pieces of it in
-new free programs; and that you know you can do these things.
-
- To protect your rights, we need to make restrictions that forbid
-anyone to deny you these rights or to ask you to surrender the rights.
-These restrictions translate to certain responsibilities for you if you
-distribute copies of the software, or if you modify it.
-
- For example, if you distribute copies of such a program, whether
-gratis or for a fee, you must give the recipients all the rights that
-you have. You must make sure that they, too, receive or can get the
-source code. And you must show them these terms so they know their
-rights.
-
- We protect your rights with two steps: (1) copyright the software,
-and (2) offer you this license which gives you legal permission to copy,
-distribute and/or modify the software.
-
- Also, for each author's protection and ours, we want to make certain
-that everyone understands that there is no warranty for this free
-software. If the software is modified by someone else and passed on, we
-want its recipients to know that what they have is not the original, so
-that any problems introduced by others will not reflect on the original
-authors' reputations.
-
- Finally, any free program is threatened constantly by software
-patents. We wish to avoid the danger that redistributors of a free
-program will individually obtain patent licenses, in effect making the
-program proprietary. To prevent this, we have made it clear that any
-patent must be licensed for everyone's free use or not licensed at all.
-
- The precise terms and conditions for copying, distribution and
-modification follow.
-
- TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-
- 0. This License applies to any program or other work which contains a
- notice placed by the copyright holder saying it may be distributed
- under the terms of this General Public License. The "Program",
- below, refers to any such program or work, and a "work based on
- the Program" means either the Program or any derivative work under
- copyright law: that is to say, a work containing the Program or a
- portion of it, either verbatim or with modifications and/or
- translated into another language. (Hereinafter, translation is
- included without limitation in the term "modification".) Each
- licensee is addressed as "you".
-
- Activities other than copying, distribution and modification are
- not covered by this License; they are outside its scope. The act
- of running the Program is not restricted, and the output from the
- Program is covered only if its contents constitute a work based on
- the Program (independent of having been made by running the
- Program). Whether that is true depends on what the Program does.
-
- 1. You may copy and distribute verbatim copies of the Program's
- source code as you receive it, in any medium, provided that you
- conspicuously and appropriately publish on each copy an appropriate
- copyright notice and disclaimer of warranty; keep intact all the
- notices that refer to this License and to the absence of any
- warranty; and give any other recipients of the Program a copy of
- this License along with the Program.
-
- You may charge a fee for the physical act of transferring a copy,
- and you may at your option offer warranty protection in exchange
- for a fee.
-
- 2. You may modify your copy or copies of the Program or any portion
- of it, thus forming a work based on the Program, and copy and
- distribute such modifications or work under the terms of Section 1
- above, provided that you also meet all of these conditions:
-
- a. You must cause the modified files to carry prominent notices
- stating that you changed the files and the date of any change.
-
- b. You must cause any work that you distribute or publish, that
- in whole or in part contains or is derived from the Program
- or any part thereof, to be licensed as a whole at no charge
- to all third parties under the terms of this License.
-
- c. If the modified program normally reads commands interactively
- when run, you must cause it, when started running for such
- interactive use in the most ordinary way, to print or display
- an announcement including an appropriate copyright notice and
- a notice that there is no warranty (or else, saying that you
- provide a warranty) and that users may redistribute the
- program under these conditions, and telling the user how to
- view a copy of this License. (Exception: if the Program
- itself is interactive but does not normally print such an
- announcement, your work based on the Program is not required
- to print an announcement.)
-
- These requirements apply to the modified work as a whole. If
- identifiable sections of that work are not derived from the
- Program, and can be reasonably considered independent and separate
- works in themselves, then this License, and its terms, do not
- apply to those sections when you distribute them as separate
- works. But when you distribute the same sections as part of a
- whole which is a work based on the Program, the distribution of
- the whole must be on the terms of this License, whose permissions
- for other licensees extend to the entire whole, and thus to each
- and every part regardless of who wrote it.
-
- Thus, it is not the intent of this section to claim rights or
- contest your rights to work written entirely by you; rather, the
- intent is to exercise the right to control the distribution of
- derivative or collective works based on the Program.
-
- In addition, mere aggregation of another work not based on the
- Program with the Program (or with a work based on the Program) on
- a volume of a storage or distribution medium does not bring the
- other work under the scope of this License.
-
- 3. You may copy and distribute the Program (or a work based on it,
- under Section 2) in object code or executable form under the terms
- of Sections 1 and 2 above provided that you also do one of the
- following:
-
- a. Accompany it with the complete corresponding machine-readable
- source code, which must be distributed under the terms of
- Sections 1 and 2 above on a medium customarily used for
- software interchange; or,
-
- b. Accompany it with a written offer, valid for at least three
- years, to give any third party, for a charge no more than your
- cost of physically performing source distribution, a complete
- machine-readable copy of the corresponding source code, to be
- distributed under the terms of Sections 1 and 2 above on a
- medium customarily used for software interchange; or,
-
- c. Accompany it with the information you received as to the offer
- to distribute corresponding source code. (This alternative is
- allowed only for noncommercial distribution and only if you
- received the program in object code or executable form with
- such an offer, in accord with Subsection b above.)
-
- The source code for a work means the preferred form of the work for
- making modifications to it. For an executable work, complete
- source code means all the source code for all modules it contains,
- plus any associated interface definition files, plus the scripts
- used to control compilation and installation of the executable.
- However, as a special exception, the source code distributed need
- not include anything that is normally distributed (in either
- source or binary form) with the major components (compiler,
- kernel, and so on) of the operating system on which the executable
- runs, unless that component itself accompanies the executable.
-
- If distribution of executable or object code is made by offering
- access to copy from a designated place, then offering equivalent
- access to copy the source code from the same place counts as
- distribution of the source code, even though third parties are not
- compelled to copy the source along with the object code.
-
- 4. You may not copy, modify, sublicense, or distribute the Program
- except as expressly provided under this License. Any attempt
- otherwise to copy, modify, sublicense or distribute the Program is
- void, and will automatically terminate your rights under this
- License. However, parties who have received copies, or rights,
- from you under this License will not have their licenses
- terminated so long as such parties remain in full compliance.
-
- 5. You are not required to accept this License, since you have not
- signed it. However, nothing else grants you permission to modify
- or distribute the Program or its derivative works. These actions
- are prohibited by law if you do not accept this License.
- Therefore, by modifying or distributing the Program (or any work
- based on the Program), you indicate your acceptance of this
- License to do so, and all its terms and conditions for copying,
- distributing or modifying the Program or works based on it.
-
- 6. Each time you redistribute the Program (or any work based on the
- Program), the recipient automatically receives a license from the
- original licensor to copy, distribute or modify the Program
- subject to these terms and conditions. You may not impose any
- further restrictions on the recipients' exercise of the rights
- granted herein. You are not responsible for enforcing compliance
- by third parties to this License.
-
- 7. If, as a consequence of a court judgment or allegation of patent
- infringement or for any other reason (not limited to patent
- issues), conditions are imposed on you (whether by court order,
- agreement or otherwise) that contradict the conditions of this
- License, they do not excuse you from the conditions of this
- License. If you cannot distribute so as to satisfy simultaneously
- your obligations under this License and any other pertinent
- obligations, then as a consequence you may not distribute the
- Program at all. For example, if a patent license would not permit
- royalty-free redistribution of the Program by all those who
- receive copies directly or indirectly through you, then the only
- way you could satisfy both it and this License would be to refrain
- entirely from distribution of the Program.
-
- If any portion of this section is held invalid or unenforceable
- under any particular circumstance, the balance of the section is
- intended to apply and the section as a whole is intended to apply
- in other circumstances.
-
- It is not the purpose of this section to induce you to infringe any
- patents or other property right claims or to contest validity of
- any such claims; this section has the sole purpose of protecting
- the integrity of the free software distribution system, which is
- implemented by public license practices. Many people have made
- generous contributions to the wide range of software distributed
- through that system in reliance on consistent application of that
- system; it is up to the author/donor to decide if he or she is
- willing to distribute software through any other system and a
- licensee cannot impose that choice.
-
- This section is intended to make thoroughly clear what is believed
- to be a consequence of the rest of this License.
-
- 8. If the distribution and/or use of the Program is restricted in
- certain countries either by patents or by copyrighted interfaces,
- the original copyright holder who places the Program under this
- License may add an explicit geographical distribution limitation
- excluding those countries, so that distribution is permitted only
- in or among countries not thus excluded. In such case, this
- License incorporates the limitation as if written in the body of
- this License.
-
- 9. The Free Software Foundation may publish revised and/or new
- versions of the General Public License from time to time. Such
- new versions will be similar in spirit to the present version, but
- may differ in detail to address new problems or concerns.
-
- Each version is given a distinguishing version number. If the
- Program specifies a version number of this License which applies
- to it and "any later version", you have the option of following
- the terms and conditions either of that version or of any later
- version published by the Free Software Foundation. If the Program
- does not specify a version number of this License, you may choose
- any version ever published by the Free Software Foundation.
-
- 10. If you wish to incorporate parts of the Program into other free
- programs whose distribution conditions are different, write to the
- author to ask for permission. For software which is copyrighted
- by the Free Software Foundation, write to the Free Software
- Foundation; we sometimes make exceptions for this. Our decision
- will be guided by the two goals of preserving the free status of
- all derivatives of our free software and of promoting the sharing
- and reuse of software generally.
-
- NO WARRANTY
-
- 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
- WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
- LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
- HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
- WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
- NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
- FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE
- QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
- PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
- SERVICING, REPAIR OR CORRECTION.
-
- 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
- WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
- MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
- LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
- INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
- INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
- DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
- OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
- OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
- ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
-
- END OF TERMS AND CONDITIONS
-
-How to Apply These Terms to Your New Programs
-=============================================
-
- If you develop a new program, and you want it to be of the greatest
-possible use to the public, the best way to achieve this is to make it
-free software which everyone can redistribute and change under these
-terms.
-
- To do so, attach the following notices to the program. It is safest
-to attach them to the start of each source file to most effectively
-convey the exclusion of warranty; and each file should have at least
-the "copyright" line and a pointer to where the full notice is found.
-
- ONE LINE TO GIVE THE PROGRAM'S NAME AND AN IDEA OF WHAT IT DOES.
- Copyright (C) 19YY NAME OF AUTHOR
-
- This program is free software; you can redistribute it and/or
- modify it under the terms of the GNU General Public License
- as published by the Free Software Foundation; either version 2
- of the License, or (at your option) any later version.
-
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU General Public License for more details.
-
- You should have received a copy of the GNU General Public License
- along with this program; if not, write to the Free Software
- Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
-
- Also add information on how to contact you by electronic and paper
-mail.
-
- If the program is interactive, make it output a short notice like
-this when it starts in an interactive mode:
-
- Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR
- Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
- type `show w'. This is free software, and you are welcome
- to redistribute it under certain conditions; type `show c'
- for details.
-
- The hypothetical commands `show w' and `show c' should show the
-appropriate parts of the General Public License. Of course, the
-commands you use may be called something other than `show w' and `show
-c'; they could even be mouse-clicks or menu items--whatever suits your
-program.
-
- You should also get your employer (if you work as a programmer) or
-your school, if any, to sign a "copyright disclaimer" for the program,
-if necessary. Here is a sample; alter the names:
-
- Yoyodyne, Inc., hereby disclaims all copyright
- interest in the program `Gnomovision'
- (which makes passes at compilers) written
- by James Hacker.
-
- SIGNATURE OF TY COON, 1 April 1989
- Ty Coon, President of Vice
-
- This General Public License does not permit incorporating your
-program into proprietary programs. If your program is a subroutine
-library, you may consider it more useful to permit linking proprietary
-applications with the library. If this is what you want to do, use the
-GNU Library General Public License instead of this License.
-
-\1f
-File: lispref.info, Node: Introduction, Next: Lisp Data Types, Prev: Copying, Up: Top
-
-Introduction
-************
-
- Most of the XEmacs text editor is written in the programming
-language called XEmacs Lisp. You can write new code in XEmacs Lisp and
-install it as an extension to the editor. However, XEmacs Lisp is more
-than a mere "extension language"; it is a full computer programming
-language in its own right. You can use it as you would any other
-programming language.
-
- Because XEmacs Lisp is designed for use in an editor, it has special
-features for scanning and parsing text as well as features for handling
-files, buffers, displays, subprocesses, and so on. XEmacs Lisp is
-closely integrated with the editing facilities; thus, editing commands
-are functions that can also conveniently be called from Lisp programs,
-and parameters for customization are ordinary Lisp variables.
-
- This manual describes XEmacs Lisp, presuming considerable familiarity
-with the use of XEmacs for editing. (See `The XEmacs Reference
-Manual', for this basic information.) Generally speaking, the earlier
-chapters describe features of XEmacs Lisp that have counterparts in many
-programming languages, and later chapters describe features that are
-peculiar to XEmacs Lisp or relate specifically to editing.
-
- This is edition 3.3.
-
-* Menu:
-
-* Caveats:: Flaws and a request for help.
-* Lisp History:: XEmacs Lisp is descended from Maclisp.
-* Conventions:: How the manual is formatted.
-* Acknowledgements:: The authors, editors, and sponsors of this manual.
-
-\1f
-File: lispref.info, Node: Caveats, Next: Lisp History, Up: Introduction
-
-Caveats
-=======
-
- This manual has gone through numerous drafts. It is nearly complete
-but not flawless. There are a few topics that are not covered, either
-because we consider them secondary (such as most of the individual
-modes) or because they are yet to be written. Because we are not able
-to deal with them completely, we have left out several parts
-intentionally. This includes most information about usage on VMS.
-
- The manual should be fully correct in what it does cover, and it is
-therefore open to criticism on anything it says--from specific examples
-and descriptive text, to the ordering of chapters and sections. If
-something is confusing, or you find that you have to look at the sources
-or experiment to learn something not covered in the manual, then perhaps
-the manual should be fixed. Please let us know.
-
- As you use this manual, we ask that you send corrections as soon as
-you find them. If you think of a simple, real life example for a
-function or group of functions, please make an effort to write it up
-and send it in. Please reference any comments to the node name and
-function or variable name, as appropriate. Also state the number of
-the edition which you are criticizing.
-
- This manual was originally written for FSF Emacs 19 and was updated
-by Ben Wing (wing@666.com) for Lucid Emacs 19.10 and later for XEmacs
-19.12, 19.13, 19.14, and 20.0. It was further updated by the XEmacs
-Development Team for 19.15 and 20.1. Please send comments and
-corrections relating to XEmacs-specific portions of this manual to
- xemacs@xemacs.org
-
- or post to the newsgroup
- comp.emacs.xemacs
-
- --Ben Wing
-
-\1f
-File: lispref.info, Node: Lisp History, Next: Conventions, Prev: Caveats, Up: Introduction
-
-Lisp History
-============
-
- Lisp (LISt Processing language) was first developed in the late
-1950's at the Massachusetts Institute of Technology for research in
-artificial intelligence. The great power of the Lisp language makes it
-superior for other purposes as well, such as writing editing commands.
-
- Dozens of Lisp implementations have been built over the years, each
-with its own idiosyncrasies. Many of them were inspired by Maclisp,
-which was written in the 1960's at MIT's Project MAC. Eventually the
-implementors of the descendants of Maclisp came together and developed a
-standard for Lisp systems, called Common Lisp.
-
- XEmacs Lisp is largely inspired by Maclisp, and a little by Common
-Lisp. If you know Common Lisp, you will notice many similarities.
-However, many of the features of Common Lisp have been omitted or
-simplified in order to reduce the memory requirements of XEmacs.
-Sometimes the simplifications are so drastic that a Common Lisp user
-might be very confused. We will occasionally point out how XEmacs Lisp
-differs from Common Lisp. If you don't know Common Lisp, don't worry
-about it; this manual is self-contained.
-
-\1f
-File: lispref.info, Node: Conventions, Next: Acknowledgements, Prev: Lisp History, Up: Introduction
-
-Conventions
-===========
-
- This section explains the notational conventions that are used in
-this manual. You may want to skip this section and refer back to it
-later.
-
-* Menu:
-
-* Some Terms:: Explanation of terms we use in this manual.
-* nil and t:: How the symbols `nil' and `t' are used.
-* Evaluation Notation:: The format we use for examples of evaluation.
-* Printing Notation:: The format we use for examples that print output.
-* Error Messages:: The format we use for examples of errors.
-* Buffer Text Notation:: The format we use for buffer contents in examples.
-* Format of Descriptions:: Notation for describing functions, variables, etc.
-
-\1f
-File: lispref.info, Node: Some Terms, Next: nil and t, Up: Conventions
-
-Some Terms
-----------
-
- Throughout this manual, the phrases "the Lisp reader" and "the Lisp
-printer" are used to refer to those routines in Lisp that convert
-textual representations of Lisp objects into actual Lisp objects, and
-vice versa. *Note Printed Representation::, for more details. You, the
-person reading this manual, are thought of as "the programmer" and are
-addressed as "you". "The user" is the person who uses Lisp programs,
-including those you write.
-
- Examples of Lisp code appear in this font or form: `(list 1 2 3)'.
-Names that represent arguments or metasyntactic variables appear in
-this font or form: FIRST-NUMBER.
-
-\1f
-File: lispref.info, Node: nil and t, Next: Evaluation Notation, Prev: Some Terms, Up: Conventions
-
-`nil' and `t'
--------------
-
- In Lisp, the symbol `nil' has three separate meanings: it is a
-symbol with the name `nil'; it is the logical truth value FALSE; and it
-is the empty list--the list of zero elements. When used as a variable,
-`nil' always has the value `nil'.
-
- As far as the Lisp reader is concerned, `()' and `nil' are
-identical: they stand for the same object, the symbol `nil'. The
-different ways of writing the symbol are intended entirely for human
-readers. After the Lisp reader has read either `()' or `nil', there is
-no way to determine which representation was actually written by the
-programmer.
-
- In this manual, we use `()' when we wish to emphasize that it means
-the empty list, and we use `nil' when we wish to emphasize that it
-means the truth value FALSE. That is a good convention to use in Lisp
-programs also.
-
- (cons 'foo ()) ; Emphasize the empty list
- (not nil) ; Emphasize the truth value FALSE
-
- In contexts where a truth value is expected, any non-`nil' value is
-considered to be TRUE. However, `t' is the preferred way to represent
-the truth value TRUE. When you need to choose a value which represents
-TRUE, and there is no other basis for choosing, use `t'. The symbol
-`t' always has value `t'.
-
- In XEmacs Lisp, `nil' and `t' are special symbols that always
-evaluate to themselves. This is so that you do not need to quote them
-to use them as constants in a program. An attempt to change their
-values results in a `setting-constant' error. *Note Accessing
-Variables::.
-
-\1f
-File: lispref.info, Node: Evaluation Notation, Next: Printing Notation, Prev: nil and t, Up: Conventions
-
-Evaluation Notation
--------------------
-
- A Lisp expression that you can evaluate is called a "form".
-Evaluating a form always produces a result, which is a Lisp object. In
-the examples in this manual, this is indicated with `=>':
-
- (car '(1 2))
- => 1
-
-You can read this as "`(car '(1 2))' evaluates to 1".
-
- When a form is a macro call, it expands into a new form for Lisp to
-evaluate. We show the result of the expansion with `==>'. We may or
-may not show the actual result of the evaluation of the expanded form.
-
- (news-cadr '(a b c))
- ==> (car (cdr '(a b c)))
- => b
-
- Sometimes to help describe one form we show another form that
-produces identical results. The exact equivalence of two forms is
-indicated with `=='.
-
- (cons 'a nil) == (list 'a)
-
-\1f
-File: lispref.info, Node: Printing Notation, Next: Error Messages, Prev: Evaluation Notation, Up: Conventions
-
-Printing Notation
------------------
-
- Many of the examples in this manual print text when they are
-evaluated. If you execute example code in a Lisp Interaction buffer
-(such as the buffer `*scratch*'), the printed text is inserted into the
-buffer. If you execute the example by other means (such as by
-evaluating the function `eval-region'), the printed text is displayed
-in the echo area. You should be aware that text displayed in the echo
-area is truncated to a single line.
-
- Examples in this manual indicate printed text with `-|',
-irrespective of where that text goes. The value returned by evaluating
-the form (here `bar') follows on a separate line.
-
- (progn (print 'foo) (print 'bar))
- -| foo
- -| bar
- => bar
-
-\1f
-File: lispref.info, Node: Error Messages, Next: Buffer Text Notation, Prev: Printing Notation, Up: Conventions
-
-Error Messages
---------------
-
- Some examples signal errors. This normally displays an error message
-in the echo area. We show the error message on a line starting with
-`error-->'. Note that `error-->' itself does not appear in the echo
-area.
-
- (+ 23 'x)
- error--> Wrong type argument: integer-or-marker-p, x
-
-\1f
-File: lispref.info, Node: Buffer Text Notation, Next: Format of Descriptions, Prev: Error Messages, Up: Conventions
-
-Buffer Text Notation
---------------------
-
- Some examples show modifications to text in a buffer, with "before"
-and "after" versions of the text. These examples show the contents of
-the buffer in question between two lines of dashes containing the buffer
-name. In addition, `-!-' indicates the location of point. (The symbol
-for point, of course, is not part of the text in the buffer; it
-indicates the place *between* two characters where point is located.)
-
- ---------- Buffer: foo ----------
- This is the -!-contents of foo.
- ---------- Buffer: foo ----------
-
- (insert "changed ")
- => nil
- ---------- Buffer: foo ----------
- This is the changed -!-contents of foo.
- ---------- Buffer: foo ----------
-
-\1f
-File: lispref.info, Node: Format of Descriptions, Prev: Buffer Text Notation, Up: Conventions
-
-Format of Descriptions
-----------------------
-
- Functions, variables, macros, commands, user options, and special
-forms are described in this manual in a uniform format. The first line
-of a description contains the name of the item followed by its
-arguments, if any. The category--function, variable, or
-whatever--appears at the beginning of the line. The description
-follows on succeeding lines, sometimes with examples.
-
-* Menu:
-
-* A Sample Function Description:: A description of an imaginary
- function, `foo'.
-* A Sample Variable Description:: A description of an imaginary
- variable,
- `electric-future-map'.
-
-\1f
-File: lispref.info, Node: A Sample Function Description, Next: A Sample Variable Description, Up: Format of Descriptions
-
-A Sample Function Description
-.............................
-
- In a function description, the name of the function being described
-appears first. It is followed on the same line by a list of parameters.
-The names used for the parameters are also used in the body of the
-description.
-
- The appearance of the keyword `&optional' in the parameter list
-indicates that the arguments for subsequent parameters may be omitted
-(omitted parameters default to `nil'). Do not write `&optional' when
-you call the function.
-
- The keyword `&rest' (which will always be followed by a single
-parameter) indicates that any number of arguments can follow. The value
-of the single following parameter will be a list of all these arguments.
-Do not write `&rest' when you call the function.
-
- Here is a description of an imaginary function `foo':
-
- - Function: foo INTEGER1 &optional INTEGER2 &rest INTEGERS
- The function `foo' subtracts INTEGER1 from INTEGER2, then adds all
- the rest of the arguments to the result. If INTEGER2 is not
- supplied, then the number 19 is used by default.
-
- (foo 1 5 3 9)
- => 16
- (foo 5)
- => 14
-
- More generally,
-
- (foo W X Y...)
- ==
- (+ (- X W) Y...)
-
- Any parameter whose name contains the name of a type (e.g., INTEGER,
-INTEGER1 or BUFFER) is expected to be of that type. A plural of a type
-(such as BUFFERS) often means a list of objects of that type.
-Parameters named OBJECT may be of any type. (*Note Lisp Data Types::,
-for a list of XEmacs object types.) Parameters with other sorts of
-names (e.g., NEW-FILE) are discussed specifically in the description of
-the function. In some sections, features common to parameters of
-several functions are described at the beginning.
-
- *Note Lambda Expressions::, for a more complete description of
-optional and rest arguments.
-
- Command, macro, and special form descriptions have the same format,
-but the word `Function' is replaced by `Command', `Macro', or `Special
-Form', respectively. Commands are simply functions that may be called
-interactively; macros process their arguments differently from functions
-(the arguments are not evaluated), but are presented the same way.
-
- Special form descriptions use a more complex notation to specify
-optional and repeated parameters because they can break the argument
-list down into separate arguments in more complicated ways.
-``[OPTIONAL-ARG]'' means that OPTIONAL-ARG is optional and
-`REPEATED-ARGS...' stands for zero or more arguments. Parentheses are
-used when several arguments are grouped into additional levels of list
-structure. Here is an example:
-
- - Special Form: count-loop (VAR [FROM TO [INC]]) BODY...
- This imaginary special form implements a loop that executes the
- BODY forms and then increments the variable VAR on each iteration.
- On the first iteration, the variable has the value FROM; on
- subsequent iterations, it is incremented by 1 (or by INC if that
- is given). The loop exits before executing BODY if VAR equals TO.
- Here is an example:
-
- (count-loop (i 0 10)
- (prin1 i) (princ " ")
- (prin1 (aref vector i)) (terpri))
-
- If FROM and TO are omitted, then VAR is bound to `nil' before the
- loop begins, and the loop exits if VAR is non-`nil' at the
- beginning of an iteration. Here is an example:
-
- (count-loop (done)
- (if (pending)
- (fixit)
- (setq done t)))
-
- In this special form, the arguments FROM and TO are optional, but
- must both be present or both absent. If they are present, INC may
- optionally be specified as well. These arguments are grouped with
- the argument VAR into a list, to distinguish them from BODY, which
- includes all remaining elements of the form.
-
-\1f
-File: lispref.info, Node: A Sample Variable Description, Prev: A Sample Function Description, Up: Format of Descriptions
-
-A Sample Variable Description
-.............................
-
- A "variable" is a name that can hold a value. Although any variable
-can be set by the user, certain variables that exist specifically so
-that users can change them are called "user options". Ordinary
-variables and user options are described using a format like that for
-functions except that there are no arguments.
-
- Here is a description of the imaginary `electric-future-map'
-variable.
-
- - Variable: electric-future-map
- The value of this variable is a full keymap used by Electric
- Command Future mode. The functions in this map allow you to edit
- commands you have not yet thought about executing.
-
- User option descriptions have the same format, but `Variable' is
-replaced by `User Option'.
-
-\1f
-File: lispref.info, Node: Acknowledgements, Prev: Conventions, Up: Introduction
-
-Acknowledgements
-================
-
- This manual was based on the GNU Emacs Lisp Reference Manual, version
-2.4, written by Robert Krawitz, Bil Lewis, Dan LaLiberte, Richard M.
-Stallman and Chris Welty, the volunteers of the GNU manual group, in an
-effort extending over several years. Robert J. Chassell helped to
-review and edit the manual, with the support of the Defense Advanced
-Research Projects Agency, ARPA Order 6082, arranged by Warren A. Hunt,
-Jr. of Computational Logic, Inc.
-
- Ben Wing adapted this manual for XEmacs 19.14 and 20.0, and earlier
-for Lucid Emacs 19.10, XEmacs 19.12, and XEmacs 19.13. He is the sole
-author of many of the manual sections, in particular the XEmacs-specific
-sections: events, faces, extents, glyphs, specifiers, toolbar, menubars,
-scrollbars, dialog boxes, devices, consoles, hash tables, range tables,
-char tables, databases, and others. The section on annotations was
-originally written by Chuck Thompson. Corrections to v3.1 and later
-were done by Martin Buchholz, Steve Baur, and Hrvoje Niksic.
-
- Corrections to the original GNU Emacs Lisp Reference Manual were
-supplied by Karl Berry, Jim Blandy, Bard Bloom, Stephane Boucher, David
-Boyes, Alan Carroll, Richard Davis, Lawrence R. Dodd, Peter Doornbosch,
-David A. Duff, Chris Eich, Beverly Erlebacher, David Eckelkamp, Ralf
-Fassel, Eirik Fuller, Stephen Gildea, Bob Glickstein, Eric Hanchrow,
-George Hartzell, Nathan Hess, Masayuki Ida, Dan Jacobson, Jak Kirman,
-Bob Knighten, Frederick M. Korz, Joe Lammens, Glenn M. Lewis, K. Richard
-Magill, Brian Marick, Roland McGrath, Skip Montanaro, John Gardiner
-Myers, Thomas A. Peterson, Francesco Potorti, Friedrich Pukelsheim,
-Arnold D. Robbins, Raul Rockwell, Per Starback, Shinichirou Sugou, Kimmo
-Suominen, Edward Tharp, Bill Trost, Rickard Westman, Jean White, Matthew
-Wilding, Carl Witty, Dale Worley, Rusty Wright, and David D. Zuhn.
-
-\1f
-File: lispref.info, Node: Lisp Data Types, Next: Numbers, Prev: Introduction, Up: Top
-
-Lisp Data Types
-***************
-
- A Lisp "object" is a piece of data used and manipulated by Lisp
-programs. For our purposes, a "type" or "data type" is a set of
-possible objects.
-
- Every object belongs to at least one type. Objects of the same type
-have similar structures and may usually be used in the same contexts.
-Types can overlap, and objects can belong to two or more types.
-Consequently, we can ask whether an object belongs to a particular type,
-but not for "the" type of an object.
-
- A few fundamental object types are built into XEmacs. These, from
-which all other types are constructed, are called "primitive types".
-Each object belongs to one and only one primitive type. These types
-include "integer", "character" (starting with XEmacs 20.0), "float",
-"cons", "symbol", "string", "vector", "bit-vector", "subr",
-"compiled-function", "hash-table", "range-table", "char-table",
-"weak-list", and several special types, such as "buffer", that are
-related to editing. (*Note Editing Types::.)
-
- Each primitive type has a corresponding Lisp function that checks
-whether an object is a member of that type.
-
- Note that Lisp is unlike many other languages in that Lisp objects
-are "self-typing": the primitive type of the object is implicit in the
-object itself. For example, if an object is a vector, nothing can treat
-it as a number; Lisp knows it is a vector, not a number.
-
- In most languages, the programmer must declare the data type of each
-variable, and the type is known by the compiler but not represented in
-the data. Such type declarations do not exist in XEmacs Lisp. A Lisp
-variable can have any type of value, and it remembers whatever value
-you store in it, type and all.
-
- This chapter describes the purpose, printed representation, and read
-syntax of each of the standard types in Emacs Lisp. Details on how to
-use these types can be found in later chapters.
-
-* Menu:
-
-* Printed Representation:: How Lisp objects are represented as text.
-* Comments:: Comments and their formatting conventions.
-* Primitive Types:: List of all primitive types in XEmacs.
-* Programming Types:: Types found in all Lisp systems.
-* Editing Types:: Types specific to XEmacs.
-* Window-System Types:: Types specific to windowing systems.
-* Type Predicates:: Tests related to types.
-* Equality Predicates:: Tests of equality between any two objects.
-
-\1f
-File: lispref.info, Node: Printed Representation, Next: Comments, Up: Lisp Data Types
-
-Printed Representation and Read Syntax
-======================================
-
- The "printed representation" of an object is the format of the
-output generated by the Lisp printer (the function `prin1') for that
-object. The "read syntax" of an object is the format of the input
-accepted by the Lisp reader (the function `read') for that object.
-Most objects have more than one possible read syntax. Some types of
-object have no read syntax; except for these cases, the printed
-representation of an object is also a read syntax for it.
-
- In other languages, an expression is text; it has no other form. In
-Lisp, an expression is primarily a Lisp object and only secondarily the
-text that is the object's read syntax. Often there is no need to
-emphasize this distinction, but you must keep it in the back of your
-mind, or you will occasionally be very confused.
-
- Every type has a printed representation. Some types have no read
-syntax, since it may not make sense to enter objects of these types
-directly in a Lisp program. For example, the buffer type does not have
-a read syntax. Objects of these types are printed in "hash notation":
-the characters `#<' followed by a descriptive string (typically the
-type name followed by the name of the object), and closed with a
-matching `>'. Hash notation cannot be read at all, so the Lisp reader
-signals the error `invalid-read-syntax' whenever it encounters `#<'.
-
- (current-buffer)
- => #<buffer "objects.texi">
-
- When you evaluate an expression interactively, the Lisp interpreter
-first reads the textual representation of it, producing a Lisp object,
-and then evaluates that object (*note Evaluation::.). However,
-evaluation and reading are separate activities. Reading returns the
-Lisp object represented by the text that is read; the object may or may
-not be evaluated later. *Note Input Functions::, for a description of
-`read', the basic function for reading objects.
-
-\1f
-File: lispref.info, Node: Comments, Next: Primitive Types, Prev: Printed Representation, Up: Lisp Data Types
-
-Comments
-========
-
- A "comment" is text that is written in a program only for the sake
-of humans that read the program, and that has no effect on the meaning
-of the program. In Lisp, a semicolon (`;') starts a comment if it is
-not within a string or character constant. The comment continues to
-the end of line. The Lisp reader discards comments; they do not become
-part of the Lisp objects which represent the program within the Lisp
-system.
-
- The `#@COUNT' construct, which skips the next COUNT characters, is
-useful for program-generated comments containing binary data. The
-XEmacs Lisp byte compiler uses this in its output files (*note Byte
-Compilation::.). It isn't meant for source files, however.
-
- *Note Comment Tips::, for conventions for formatting comments.
-
-\1f
-File: lispref.info, Node: Primitive Types, Next: Programming Types, Prev: Comments, Up: Lisp Data Types
-
-Primitive Types
-===============
-
- For reference, here is a list of all the primitive types that may
-exist in XEmacs. Note that some of these types may not exist in some
-XEmacs executables; that depends on the options that XEmacs was
-configured with.
-
- * bit-vector
-
- * buffer
-
- * char-table
-
- * character
-
- * charset
-
- * coding-system
-
- * cons
-
- * color-instance
-
- * compiled-function
-
- * console
-
- * database
-
- * device
-
- * event
-
- * extent
-
- * face
-
- * float
-
- * font-instance
-
- * frame
-
- * glyph
-
- * hash-table
-
- * image-instance
-
- * integer
-
- * keymap
-
- * marker
-
- * process
-
- * range-table
-
- * specifier
-
- * string
-
- * subr
-
- * subwindow
-
- * symbol
-
- * toolbar-button
-
- * tooltalk-message
-
- * tooltalk-pattern
-
- * vector
-
- * weak-list
-
- * window
-
- * window-configuration
-
- * x-resource
-
- In addition, the following special types are created internally but
-will never be seen by Lisp code. You may encounter them, however, if
-you are debugging XEmacs. The printed representation of these objects
-begins `#<INTERNAL EMACS BUG', which indicates to the Lisp programmer
-that he has found an internal bug in XEmacs if he ever encounters any
-of these objects.
-
- * char-table-entry
-
- * command-builder
-
- * extent-auxiliary
-
- * extent-info
-
- * lcrecord-list
-
- * lstream
-
- * opaque
-
- * opaque-list
-
- * popup-data
-
- * symbol-value-buffer-local
-
- * symbol-value-forward
-
- * symbol-value-lisp-magic
-
- * symbol-value-varalias
-
- * toolbar-data
-
-\1f
-File: lispref.info, Node: Programming Types, Next: Editing Types, Prev: Primitive Types, Up: Lisp Data Types
-
-Programming Types
-=================
-
- There are two general categories of types in XEmacs Lisp: those
-having to do with Lisp programming, and those having to do with
-editing. The former exist in many Lisp implementations, in one form or
-another. The latter are unique to XEmacs Lisp.
-
-* Menu:
-
-* Integer Type:: Numbers without fractional parts.
-* Floating Point Type:: Numbers with fractional parts and with a large range.
-* Character Type:: The representation of letters, numbers and
- control characters.
-* Symbol Type:: A multi-use object that refers to a function,
- variable, or property list, and has a unique identity.
-* Sequence Type:: Both lists and arrays are classified as sequences.
-* Cons Cell Type:: Cons cells, and lists (which are made from cons cells).
-* Array Type:: Arrays include strings and vectors.
-* String Type:: An (efficient) array of characters.
-* Vector Type:: One-dimensional arrays.
-* Bit Vector Type:: An (efficient) array of bits.
-* Function Type:: A piece of executable code you can call from elsewhere.
-* Macro Type:: A method of expanding an expression into another
- expression, more fundamental but less pretty.
-* Primitive Function Type:: A function written in C, callable from Lisp.
-* Compiled-Function Type:: A function written in Lisp, then compiled.
-* Autoload Type:: A type used for automatically loading seldom-used
- functions.
-* Char Table Type:: A mapping from characters to Lisp objects.
-* Hash Table Type:: A fast mapping between Lisp objects.
-* Range Table Type:: A mapping from ranges of integers to Lisp objects.
-* Weak List Type:: A list with special garbage-collection properties.
-
-\1f
-File: lispref.info, Node: Integer Type, Next: Floating Point Type, Up: Programming Types
-
-Integer Type
-------------
-
- The range of values for integers in XEmacs Lisp is -134217728 to
-134217727 (28 bits; i.e., -2**27 to 2**27 - 1) on most machines. (Some
-machines, in particular 64-bit machines such as the DEC Alpha, may
-provide a wider range.) It is important to note that the XEmacs Lisp
-arithmetic functions do not check for overflow. Thus `(1+ 134217727)'
-is -134217728 on most machines. (However, you *will* get an error if
-you attempt to read an out-of-range number using the Lisp reader.)
-
- The read syntax for integers is a sequence of (base ten) digits with
-an optional sign at the beginning. (The printed representation produced
-by the Lisp interpreter never has a leading `+'.)
-
- -1 ; The integer -1.
- 1 ; The integer 1.
- +1 ; Also the integer 1.
- 268435457 ; Causes an error on a 28-bit implementation.
-
- *Note Numbers::, for more information.
-
-\1f
-File: lispref.info, Node: Floating Point Type, Next: Character Type, Prev: Integer Type, Up: Programming Types
-
-Floating Point Type
--------------------
-
- XEmacs supports floating point numbers. The precise range of
-floating point numbers is machine-specific.
-
- The printed representation for floating point numbers requires either
-a decimal point (with at least one digit following), an exponent, or
-both. For example, `1500.0', `15e2', `15.0e2', `1.5e3', and `.15e4'
-are five ways of writing a floating point number whose value is 1500.
-They are all equivalent.
-
- *Note Numbers::, for more information.
-
projects / chise / xemacs-chise.git.1 / blobdiff