--- /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 / blobdiff