-This is ../info/lispref.info, produced by makeinfo version 4.0 from
+This is ../info/lispref.info, produced by makeinfo version 4.6 from
lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
* Copying:: Conditions for copying and changing XEmacs.
* Introduction:: Introduction and conventions used.
+* Packaging:: Lisp library administrative infrastructure.
+
* Lisp Data Types:: Data types of objects in XEmacs Lisp.
* Numbers:: Numbers and arithmetic functions.
* Strings and Characters:: Strings, and functions that work on them.
* A Sample Function Description::
* A Sample Variable Description::
+Packaging
+
+* Package Overview:: Lisp Libraries and Packages.
+* Package Terminology:: Basic stuff.
+* Building Packages:: Turn packaged source into a tarball.
+* Local.rules File:: Tell the XEmacs Packaging System about your host.
+* Creating Packages:: Tell the XEmacs Packaging System about your package.
+* Issues::
+
+Package Overview
+
+* The User View::
+* The Library Maintainer View::
+* The Package Release Engineer View::
+
+The Library Maintainer's View
+
+* Infrastructure:: Global Makefiles and common rules.
+* Control Files:: Package-specific Makefiles and administrative files.
+* Obtaining:: Obtaining the XEmacs Packaging System and utilities.
+
+Creating Packages
+
+* package-info.in:: package-info.in
+* Makefile:: `Makefile'
+* Makefile Targets::
+
Lisp Data Types
* Printed Representation:: How Lisp objects are represented as text.
* Retrieving Specifications:: Querying a specifier's specifications.
* Specifier Instancing Functions::
Functions to instance a specifier.
-* Specifier Example:: Making all this stuff clearer.
+* Specifier Examples:: Making all this stuff clearer.
* Creating Specifiers:: Creating specifiers for your own use.
* Specifier Validation Functions::
Validating the components of a specifier.
* Redisplay Glyphs:: Glyphs controlling various redisplay functions.
* Subwindows:: Inserting an externally-controlled subwindow
into a buffer.
+* Glyph Examples:: Examples of how to work with glyphs.
Glyph Functions
* Pure Storage:: A kludge to make preloaded Lisp functions sharable.
* Garbage Collection:: Reclaiming space for Lisp objects no longer used.
+\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: Packaging, 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.
+
+ 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 (ben@xemacs.org) 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: Packaging, Next: Lisp Data Types, Prev: Introduction, Up: Top
+
+The XEmacs Packaging System
+***************************
+
+The XEmacs distribution, starting with version 21, comes only with a
+very basic set of built-in modes and libraries. Most of the libraries
+that were part of the distribution of earlier versions of XEmacs are now
+available separately. The user as well as the system administrator can
+choose which packages to install; the actual installation process is
+easy. This gives an installer the ability to tailor an XEmacs
+installation for local needs with safe removal of unnecessary code.
+
+ This chapter describes how to package Lisp libraries for use with the
+XEmacs Packaging System.
+
+ _Please note carefully_ that the term "package" as used in XEmacs
+refers to an aggregation of Lisp code and/or data distributed as a
+unit. It does not, as it does in many Lisps, refer to a way of
+creating separate name spaces. XEmacs has no facility for providing
+separate name spaces. (If we ever do get separate name spaces, we'll
+probably regret overloading the nomenclature in this way, but it's
+become established.)
+
+* Menu:
+
+Introduction:
+* Package Overview:: Lisp Libraries and Packages.
+
+Packaging Lisp Libraries:
+* Package Terminology:: Basic stuff.
+* Building Packages:: Turn packaged source into a tarball.
+* Makefile Targets:: Package `Makefile' targets
+* Local.rules File:: Tell the XEmacs Packaging System about your host.
+* Creating Packages:: Tell the XEmacs Packaging System about your package.
+* Documenting Packages:: Explain your package to users and hackers.
+
+Internals and Package Release Engineering:
+* Issues::
+
+\1f
+File: lispref.info, Node: Package Overview, Next: Package Terminology, Up: Packaging
+
+An overview of the XEmacs Packaging System
+******************************************
+
+The XEmacs Packaging System is a system for administering the
+installation, upgrade, and removal of Lisp libraries. For the end
+user, it provides facilities for determining availability of packages
+and which versions at remote sites. It will download and automatically
+install a package, ensuring that any old files from previous versions
+of the package are removed first. By providing a standard set of
+hierarchies for installation, it makes configuration of XEmacs simpler.
+Furthermore, packages normally provide ancillary auto-autoloads and
+custom-loads libraries, which are automatically detected and loaded by
+XEmacs upon startup. This means that once installed, all facilities of
+package, including autoloading the library upon invocation of a command
+provided by the library and convenient configuration and customization,
+are automatically available to the user. There is no need to add
+autoloads or keybindings to in the init file, and structured
+configuration of the package is available through the Customize system
+even before the libraries are loaded.
+
+ All of this convenience comes at a cost. The cost of administration
+at the package level is negligible compared to the benefits, of course.
+However, the requirement that XEmacs find and load auto-autoloads and
+custom-loads libraries comes at a fairly large cost in startup time. In
+order to reduce this cost, XEmacs imposes fairly strict conditions on
+the structure of an installed package.
+
+ Meeting these requirements, as well as simply providing the
+auto-autoloads and the information about availability and so on does
+impose some costs on the library maintainer. The XEmacs Packaging
+System also provides structure and utilities to the library maintainer
+to make these tasks easier. This manual documents the requirements and
+the tools that the XEmacs Packaging System provides to ensure that a
+package satisfies them.
+
+* Menu:
+
+* The User View::
+* The Library Maintainer View::
+* The Package Release Engineer View::
+
+\1f
+File: lispref.info, Node: The User View, Next: The Library Maintainer View, Up: Package Overview
+
+The User View
+=============
+
+*N.B.* Much of the discussion in this section undoubtedly belongs
+elsewhere, *Note Packages: (xemacs)Packages.
+
+ From the user's point of view, an XEmacs binary package is simply a
+standard tarball (usually gzipped) containing Lisp sources, compiled
+Lisp, documentation, and possibly data files or supporting executables.
+The tarball is unpacked using standard tools such as GNU tar and gzip.
+The package system does impose certain requirements for automatic
+configuration to work.
+
+ Here the main consideration is that the tarball "expects" to be
+unpacked from the top of a package hierarchy. A "package hierarchy" is
+basically an image of a classic Emacs "run-in-place" tree, with `lisp',
+`etc', `info', `man', `lib-src', and `pkginfo' subdirectories of the
+top. The `pkginfo' subdirectory is for use by the XEmacs Packaging
+System administration tools, and currently contains a
+`MANIFEST.PACKAGE-NAME' file for each package to ensure that no cruft
+remains when a package is removed or updated. The `lisp', `etc', and
+`lib-src' subdirectories are further subdivided, with a subdirectory
+for each package. The `info' directory obeys the usual conventions.
+_I.e._, the `info' directory is flat with a(n) (optional) `dir' file
+and one (set of) info file(s) per package. The `man' subdirectory
+typically contains documentation sources, separated by package. (It
+does not contain `man(1)' pages, as Emacs provides very few of them.)
+
+ There are several standard package hierarchies, and administrators
+can configure others at build time, while users can configure others at
+run time. The standard system hierarchies are all subdirectories of an
+XEmacs installation root, typically `/usr/local/lib/xemacs/'. These
+are the `xemacs-packages', `mule-packages', `infodock-packages', and
+`site-packages' hierarchies. Each has the structure described above,
+but the purposes differ. The `xemacs-packages' is the normal place for
+installing "official" packages and many third-party libraries.
+Unfortunately, it is not yet quite possible to read libraries
+containing international characters with a non-Mule XEmacs, so such
+libraries are sequestered in the `mule-packages' hierarchy. Some
+packages are compatible only with the Infodock development environment,
+and they will be installed in the `infodock-packages' hierarchy. The
+`site-packages' hierarchy is for packages not distributed by
+XEmacs.org, typically locally developed.
+
+ Packages are in principle supposed to be XEmacs version-independent,
+but if such dependencies are unavoidable, additional standard package
+hierarchies may be installed under version directories, _e.g._
+`/usr/local/lib/xemacs-21.4.6/'.
+
+ Users who do not have sufficient privilege to install packages in the
+system hierarchies may install package hierarchies under `~/.xemacs'.
+At present only the `xemacs-packages', `mule-packages', and
+`site-packages' hierarchies are supported, but it might make sense to
+extend this to support `infodock-packages' hierarchies in the future.
+
+ The package hierarchies are not searched directly for libraries to be
+loaded; this would be very costly. Instead, the hierarchies are ordered
+according to certain rules, and searched for package lisp directories at
+invocation. These directories are added to the general `load-path'.
+As usual, it is `load-path' that is searched at run-time. This
+approach is somewhat costly at initialization, but results in a very
+"clean" `load-path'.
+
+ The order of search can be changed at build time by specifying the
+`--package-path' option to `configure', or at run-time by specifying
+the `EMACSPACKAGEPATH' environment variable. *Note Packages:
+(xemacs)Packages.
+
+ The default order of search is hierarchically determined. First, the
+roots are ordered. The "early" roots are the user-specific roots,
+typically `~/.xemacs'. The "late" roots are the system roots,
+typically `/usr/local/lib/xemacs-21.4.6' and `/usr/local/lib/xemacs',
+in that order. All hierarchies for a given root are searched for
+package Lisp directories, which are appended to `load-path' in the
+order found. Then the search proceeds to the next root, whose results
+will be appended to the `load-path' generated by previous roots.
+
+ Second, the hierarchies below each root are searched in the order
+`site-packages', `infodock-packages', `mule-packages', then
+`xemacs-packages'.
+
+ In each hierarchy there should be a `lisp' subdirectory, containing
+directories named for the packages. Each package's Lisp libraries thus
+are contained in a directory of the form ROOT/HIERARCHY/lisp/PACKAGE/.
+
+ With such a complex search algorithm, the possibility of libraries
+being shadowed by another library with the same name is quite real.
+There are two considerations here. First, every XEmacs package
+contains certain libraries with constant names. These are
+
+`_pkg.el'
+ Lisp code to inform the package administration system about the
+ package
+
+`auto-autoloads.el'
+ Lisp code to set up autoloaded functions and variables that may be
+ needed at load time
+
+`custom-load.el'
+ definitions of configuration variables for use with the Customize
+ system.
+
+ They are special-cased, because the way they are used prevents
+shadowing from being an issue.
+
+ Second, it is possible that multiple copies of some library, or
+different libraries with the same name, are installed in various places
+in the hierarchies. To detect such shadows, use
+`list-load-path-shadows'.
+
+ Finally, note that most basic Emacs functionality, including most of
+the Lisp API, is implemented in Lisp libraries. Because they use
+internal reserved APIs that are subject to change according the needs
+of the developers, these libraries are distributed with the XEmacs
+binary, and are called "core Lisp libraries". Most core Lisp libraries
+are "preloaded" into the Emacs binary and in normal usage are never
+explicitly loaded. However, they can be explicitly loaded, and if so
+they are searched on `load-path'. Furthermore, functions such as
+`locate-library' will also search on the `load-path'. The searching
+takes place under somewhat different rules from those used for packaged
+Lisp. It is probably easiest to think of the package hierarchy
+searching algorithm as receiving a `load-path' initialized to the core
+Lisp directories.
+
+\1f
+File: lispref.info, Node: The Library Maintainer View, Next: The Package Release Engineer View, Prev: The User View, Up: Package Overview
+
+The Library Maintainer View
+===========================
+
+From the library maintainer's viewpoint, the advantages to the XEmacs
+Packaging System stem from the convenience to the user of installation
+and upgrade. Since an installed package automatically registers its
+entry points via autoload and its configuration variables with the
+Customize system, configuration FAQs are reduced. When it's easy to
+upgrade, users learn to try `Tools | Packages | Update Installed
+Packages' before posting a FAQ whose answer is "long since fixed,
+please upgrade."
+
+ This comes at some cost, as the library maintainer needs to arrange
+that the package be installed in a directory structure that satisfies
+the requirements of the XEmacs Packaging System. Autoload cookies and
+defcustoms must also be added to existing libraries. The XEmacs
+Packaging System provides infrastructure to assure that all of these
+annoyances need only be dealt with once. The autoload cookies and
+defcustoms are beyond the scope of this chapter, but most maintainers
+of modern packages are already familiar with these mechanisms.
+
+ The XEmacs Packaging System may be divided into the "infrastructure"
+common to all packages, and the package-specific "control files". The
+infrastructure supports global builds, installation, and generation of
+the "sumo" bundles of packages, as well as generation of individual
+packages. The package control files describe the structure of the
+package's source tree and provide administrative information.
+
+* Menu:
+
+* Infrastructure:: Global Makefiles and common rules.
+* Control Files:: Package-specific Makefiles and administrative files.
+* Obtaining:: Obtaining the XEmacs Packaging System and required utilities.
+
+\1f
+File: lispref.info, Node: Infrastructure, Next: Control Files, Up: The Library Maintainer View
+
+Infrastructure
+--------------
+
+In order to get the greatest benefit from the XEmacs Packaging System,
+a library maintainer should place the package sources in an appropriate
+place in the XEmacs source package hierarchy, and arrange to have the
+source package imported into the XEmacs CVS repository. (We realize
+that the latter requirement can be quite burdensome. We are working on
+ways to remove this requirement, but for the present it remains
+necessary.) The library maintainer must also keep sources for any
+packages his/her package requires. This requirement is somewhat
+burdensome, but unlikely to be relaxed because of the implementation of
+compilation of macros in Emacs Lisp. Macros cannot be called by
+compiled Lisp (the macro expansion, which is always known at compile
+time, is inlined), so the source of the macro must be loaded before
+compiling the called function.
+
+ The source package hierarchy may be rooted anywhere. The CVS module
+is called "packages," so we will refer to the top directory of the
+source package hierarchy as "the `packages' directory." The `packages'
+directory contains two source subdirectories, `xemacs-packages' and
+`mule-packages' (for convenience in segregating the packages which
+depend on Mule, as they will cause load-time errors in a non-Mule
+XEmacs). Each subdirectory contains many package source directories,
+whose internal structure is not specified. That structure is left up
+to the convenience of the library maintainers. The requirements on the
+top directory of an individual package source tree are given below,
+*Note Control Files::.
+
+ The `packages' directory contains some auxiliary Lisp libraries used
+in the compilation and packaging process. The content of these
+libraries is of interest primarily to the packaging engineers, *Note
+The Package Release Engineer View::.
+
+ Finally, the `packages', `packages/xemacs-packages', and
+`packages/mule-packages' directories contain `Makefile's and include
+files to control the package creation process. The `Makefile's in
+`packages/xemacs-packages' and `packages/mule-packages' simply define
+the default sets of known packages and include `../iterate.rules',
+which implements recursive building of all target packages.
+
+ The `make' infrastructure in `packages' includes
+
+`Makefile'
+ controls building of individual packages, local installation, and
+ bundling of "sumo" tarballs
+
+`iterate.rules'
+ controls recursive builds of multiple packages
+
+`meta-iterate.rules'
+ This is used by higher-level subdirectories that do not directly
+ contain packages. Subdirectories directly containing packages
+ should use iterate.rules instead.
+
+`XEmacs.rules'
+ provides the rules for building and packaging. Included by all
+ package `Makefile's.
+
+`Local.rules'
+ provides local configuration, such as installation targets and
+ staging directories, as well as a number of kludges (many now
+ obsolete) required for building packages on the Windows platform.
+
+`Local.rules.template'
+ a template for Local.rules, liberally commented
+
+`Local.rules.mk'
+ consistency checking for `Local.rules', included by both the
+ top-level `Makefile' and by `XEmacs.rules'.
+
+`Local.rules.inc'
+ a file to `include' in package `Makefile's to be able to get at
+ variables in `Local.rules' _before_ including `XEmacs.rules'.
+
+`package-compile.el'
+ compile environment (_e.g._, load-path) setup.
+
+ Of these, only `Local.rules' and `package-compile.el' need to be
+modified by the library maintainer. The changes to Local.rules affect
+only your environment. This should need to be done only once when
+first preparing the source environment. The necessary modifications to
+`package-compile.el' need to be done for each package and are discussed
+in the next section, *Note Control Files::.
+
+\1f
+File: lispref.info, Node: Control Files, Next: Obtaining, Prev: Infrastructure, Up: The Library Maintainer View
+
+Control Files
+-------------
+
+Each package source must contain a number of control files in the
+top-level directory. These files in general can be created and then
+ignored, except for a few variables that need to be updated when new
+versions are released. In most cases even adding, renaming, and
+removing library source files can be handled by generic rules.
+
+ The package control files include
+
+`Makefile'
+ Must set a few `make' variables used by the administrative
+ utilities, and defines a couple of package-building targets to
+ depend on appropriate targets defined generically in
+ `XEmacs.rules'. It may also provide various variables and rules
+ to transform the source tree structure into that expected by the
+ run-time system.
+
+`package-info.in'
+ Provides a template for package information to be provided to the
+ administrative utilities. Static variables that are rarely changed
+ (such as the package's name) are entered as literals. Some
+ variables are generated by the build process (build dates and MD5
+ checksums) and are automatically filled in. Finally, some
+ variables that change irregularly (dependences and even version
+ numbers) are set as `make' variables in the `Makefile'.
+
+`ChangeLog'
+ Not strictly required, but normally a ChangeLog will be added by
+ the XEmacs package maintainer if different from the upstream
+ maintainer.
+
+`_pkg.el'
+ Generated. Simply does a `package-provide' for the package.
+
+`auto-autoloads.el'
+ Generated. Read when XEmacs is initialized, and provides
+ autoloads for defuns and other forms in the sources that are
+ marked with an "autoload cookie" (`;;;###autoload'.
+
+`custom-loads.el'
+ Generated. Read when XEmacs is initialized, and informs the
+ Customize subsystem how to find the defcustom forms needed to
+ create Customization forms for the usre configuration variables of
+ the package.
+
+\1f
+File: lispref.info, Node: Obtaining, Prev: Control Files, Up: The Library Maintainer View
+
+Obtaining the XEmacs Packaging System and Required Utilities
+------------------------------------------------------------
+
+Currently both the infrastructure for creating XEmacs packages and the
+package sources themselves are available only by CVS. See
+`http://www.xemacs.org/Develop/cvsaccess.html' for more intformation.
+
+ The XEmacs Packaging System currently requires GNU `make', and
+XEmacs, to build packages.
+
+\1f
+File: lispref.info, Node: The Package Release Engineer View, Prev: The Library Maintainer View, Up: Package Overview
+
+The Package Release Engineer View
+---------------------------------
+
+The XEmacs Package Release Engineer is responsible for keeping the
+system coherent. The changes to `packages/package-compile.el' and
+`packages/xemacs-packages/Makefile' required to make the package
+available to others, and for building SUMO tarballs, _etc_, are done by
+the Package Release Engineer, not individual library maintainers.
+
+ The Package Release Engineer also maintains assorted infrastructure
+for actually making releases. These are generally available for
+inspection in the `xemacs-builds' module in the CVS repository.
+
+\1f
+File: lispref.info, Node: Package Terminology, Next: Building Packages, Prev: Package Overview, Up: Packaging
+
+Package Terminology:
+====================
+
+Libraries and Packages
+----------------------
+
+A Lisp "library" is a single loadable file containing Lisp code. It
+may be in source or byte-compiled form. A Lisp "package" is a set of
+one or more libraries, usually related to each other in some way,
+bundled with administrative information for convenient distribution.
+
+Package Flavors
+---------------
+
+There are two main flavors of packages.
+
+*Regular Packages*
+ A regular package is a set of Lisp libraries design to cooperate
+ with one another. A very complex example is Gnus. One may not in
+ general safely remove any of the component libraries.
+
+*Single-File Packages*
+ A single-file package is a collection of thematically related but
+ otherwise independent Lisp libraries. These libraries are bundled
+ together for convenience of the maintainers. Usually individual
+ libraries may be deleted at will without any loss of functionality
+ of other libraries in the package. However, we would recommend
+ that you follow this rule of thumb: "When in doubt, don't delete".
+ If it's really that big a deal, request that the maintainers
+ split the package into smaller aggregations.
+
+Package Distributions
+---------------------
+
+XEmacs Lisp packages are distributed in two ways. "Binary packages"
+are used by system administrators and end users. They are packaged in a
+form convenient for direct installation into an XEmacs package
+hierarchy. "Source packages" are for developers and include all files
+necessary for rebuilding byte-compiled lisp and creating tarballs for
+distribution or installation. This is all of the package author's
+source code plus all of the files necessary to build distribution
+tarballs (Unix Tar format files, gzipped for space savings).
+(Occasionally sources that are not relevant to XEmacs are usually
+renamed to `file.upstream'.)
+
+ Currently, source packages are only available via CVS. See
+<http://www.xemacs.org/Develop/cvsaccess.html> for details.
+
+ The package distributions are also split according to major features
+required in XEmacs to support them. At present there are "generic"
+packages, which can be loaded by _any_ XEmacs, and "Mule" packages,
+which _require_ Mule support or they will cause errors when loaded.
+Note that there is no guarantee that a generic package will have any
+useful functionality in a minimally configured XEmacs. As long as any
+XEmacs can successfully load the package's libraries (perhaps given
+other required Lisp libraries), it will be classified as generic. At
+the present time only Mule packages need be treated specially, and even
+those only if they contain multibyte characters.
+
+\1f
+File: lispref.info, Node: Building Packages, Next: Makefile Targets, Prev: Package Terminology, Up: Packaging
+
+Building Packages:
+==================
+
+Currently, source packages are only available via anonymous CVS. See
+<http://www.xemacs.org/Develop/cvsaccess.html> for details of checking
+out the `packages' module.
+
+Prerequisites for Building Source Packages
+------------------------------------------
+
+`GNU cp'
+
+`GNU install'
+ (or a BSD compatible install program).
+
+`GNU make'
+ (3.79 or later preferred).
+
+`makeinfo'
+ (4.2 from texinfo-4.2)
+
+`GNU tar'
+ (or equivalent).
+
+`GNU gzip'
+ (or equivalent).
+
+`A properly configured `Local.rules' file.'
+ *Note Local.rules File::.
+
+ And of course, XEmacs, 21.0 or higher.
+
+What You Can Do With Source Packages
+====================================
+
+The packages CVS sources are most useful for creating XEmacs package
+tarballs for installation into your own XEmacs installations or for
+distributing to others.
+
+ It should be noted that most of the package `Makefile's do _not_
+need to contain _any_ target rules. Everything is handled from the
+`XEmacs.rules' file, located in the toplevel directory of the packages
+source tree.
+
+\1f
+File: lispref.info, Node: Makefile Targets, Next: Local.rules File, Prev: Building Packages, Up: Packaging
+
+`Makefile' targets
+******************
+
+The following targets can be used when running `make' to build the
+packages:
+
+`mostlyclean'
+ Removes any documentation files that have been processed by TeX.
+
+`clean'
+ Does a `mostlyclean', plus removes generated postscript and dvi
+ files. Also removes any generated .elc files, along with the
+ normal .elc files in the package and HTML and .info files.
+
+`distclean'
+ Use this when preparing a distribution. It kills anything that
+ can be rebuilt.
+
+`extraclean'
+ Does a `distclean' and also removes any backup files (`*~') and
+ `core' files.
+
+`package-info'
+ Creates the `package-info' file from the `package-info.in' and
+ writes an entry in the `package-index' file.
+
+`bindist'
+ Builds the package, including any Texinfo documentation (info
+ format), writes an entry into the `package-index' file and builds
+ a tarball of the package. Also writes an entry into
+ `setup-packages.ini' which is later used in the creation of
+ netinstaller's `setup.ini'.
+
+`install'
+ Builds and installs a package
+
+`install-only'
+ Doesn't build anything, just installs it.
+
+`autoloads'
+ Generate the package's `auto-autoloads.el' file.
+
+`binkit'
+ Creates the directories needed for installation and copies the
+ files there. Basically this is an alias for `install-only'.
+
+`html'
+ Builds the HTML versions of the documentation.
+
+`compile'
+ Does most of the work. Builds the elcs, infos at a minimum.
+
+The targets that most people would be interested in would be:
+-------------------------------------------------------------
+
+ * `all'
+
+ * `bindist'
+
+ * `html'
+
+ * `install'
+
+ * `install-only'
+
+ * `clean'
+
+ * `distclean'
+
+\1f
+File: lispref.info, Node: Local.rules File, Next: Creating Packages, Prev: Makefile Targets, Up: Packaging
+
+The Local.rules File:
+=====================
+
+This file in `packages' provides the XEmacs Packaging System with
+information about the local configuration and environment. To create
+`Local.rules', simply copy `Local.rules.template' from that directory to
+`Local.rules' and edit it to suit your needs.
+
+ These are the variables in `Local.rules' that you may need to
+provide values for:
+
+`XEMACS'
+ The name (and path if needed) of the XEmacs binary to use for
+ building the packages. The default is `xemacs'.
+
+`XEMACS_21_5'
+ This will enable some, as yet, unimplemented features in XEmacs
+ 21.5 and above. For now leave this blank (the default) regardless
+ of the XEmacs version you are using.
+
+`BUILD_WITHOUT_MULE'
+ Set this to `t' if you are using a non-Mule XEmacs. The default is
+ that this variable is not set (blank) which means to build _with_
+ Mule.
+
+`XEMACS_NATIVE_NT'
+ Set this to `t' if you are using a native Microsoft Windows build
+ of XEmacs (not a Cygwin build) to build the packages. *N.B.* To
+ Windows users, you still need the Cygwin environment to actually
+ build the packages.
+
+`XEMACS_INSTALLED_PACKAGES_ROOT'
+ Set this to the root of where you want the packages to be
+ installed. Under this directory will hang `xemacs-packages' and
+ `mule-packages'. See NONMULE_INSTALLED_PACKAGES_ROOT and
+ MULE_INSTALLED_PACKAGES_ROOT. The default for this is
+ `/usr/local/lib/xemacs'. Which may not be what you want if you are
+ developing XEmacs. To quote the comments in
+ `Local.rules.template':
+
+ If you are developing XEmacs, you probably don't want to
+ install the packages under /usr/local, which is where the
+ stable, released version of XEmacs goes. Instead, we suggest
+ a layout as described in the base README file of recent
+ versions of XEmacs. In a nutshell, we suggest you put your
+ source under /src/xemacs, and under this put the package
+ sources in package-src/, and the installed packages in
+ xemacs-packages/ and mule-packages/. If you do everything
+ this way, you might want to set things as follows:
+
+ XEMACS_INSTALLED_PACKAGES_ROOT = ${XEMACS_PACKAGES_BASE}/..
+
+ which puts the xemacs-packages/ and mule-packages/
+ directories as sisters of the package-src/ directory, and you
+ have to tell configure the location of the installed packages
+ using `-package-path', something like
+
+ configure
+ -package-path=/src/xemacs/xemacs-packages;/src/xemacs/mule-packages
+
+`symlink'
+ The default is unset (blank). If you set this to `t' then `make
+ install' will create a "symlink farm" of the installed packages
+ under XEMACS_INSTALLED_PACKAGES_ROOT. Obviously, for this to
+ work, your system has to support symbolic links. This is as close
+ as you can get to "running in place" for the packages.
+
+`NONMULE_INSTALLED_PACKAGES_ROOT'
+ This is where the non-Mule packages get installed to. The default
+ is `${XEMACS_INSTALLED_PACKAGES_ROOT}/xemacs-packages'.
+
+`MULE_INSTALLED_PACKAGES_ROOT'
+ This is where the Mule packages get installed to. The default is
+ `${XEMACS_INSTALLED_PACKAGES_ROOT}/mule-packages'.
+
+`NONMULE_PACKAGES'
+ A whitespace separated list of non-Mule packages to build/install.
+
+ NONMULE_PACKAGES = bbdb gnus xemacs-base prog-modes
+
+ The value for this variable can also be the symbol
+ `xemacs-packages', which means to build/install _all_ of the
+ non-Mule packages. The default is `xemacs-packages'.
+
+`MULE_PACKAGES'
+ A whitespace separated list of Mule packages to build/install.
+
+ MULE_PACKAGES = mule-base leim locale
+
+ The value for this variable can also be the symbol
+ `mule-packages', which means to build/install _all_ of the Mule
+ packages. The default is `mule-packages'.
+
+`PACKAGE_INDEX'
+ The name of the package-index file. The default is `package-index'
+ and you probably don't need to worry about changing it.
+
+`INSTALL'
+ The path to a BSD compatible install program. The default is
+ `install -c'.
+
+`TAR'
+ The path to GNU/tar. The default is `tar'.
+
+`BZIP2'
+ The path to the bzip2 compression program. The default is unset
+ (blank). If this is set `.tar.bz2' archives will be built _in
+ addition to_ the `.tar.gz' archives.
+
+`EXCLUDES'
+ For things that you _don't_ want to go into the package tarballs.
+ It takes the same format as GNU/tar's `--exclude' option. The
+ default is:
+
+ EXCLUDES = \
+ --exclude 'CVS' \
+ --exclude 'RCS' \
+ --exclude 'SCCS' \
+ --exclude '*~' \
+ --exclude '*.orig' \
+ --exclude '*.rej' \
+ --exclude '.\#*'
+
+`VANILLA'
+ Set to the XEmacs command line option that forces running in
+ "vanilla" mode. The default is `-vanilla'. You wouldn't ever
+ need to alter this.
+
+`BATCH'
+ How to put XEmacs into "batch" mode. It also sets a couple of
+ other things and in the normal course of events you wouldn't need
+ to alter this from the default which is:
+
+ BATCH = $(VANILLA) -batch -eval \
+ '(setq stack-trace-on-error t \
+ load-always-display-messages t \
+ load-ignore-out-of-date-elc-files t \
+ load-show-full-path-in-messages t)'
+
+`MAKEINFO'
+ The path to `makeinfo'. The default is `makeinfo'
+
+`INSTALL_HTML'
+ Set this to `t' if you want to install HTML versions of the Texinfo
+ documentation. The default is unset (blank).
+
+`TEXI2HTML'
+ The path to the program that can convert Texinfo source to HTML.
+ The default is `texi2html'.
+
+`TEXI2DVI'
+ The path to the program that can convert Texinfo source to DVI.
+ The default is `texi2dvi'
+
+`DVIPS'
+ The path to the program that can convert DVI to Postscript. The
+ default is `dvips'
+
+`TEXI2PDF'
+ The path to the program that can convert Texinfo source to PDF
+ format. The default is `texi2pdf'.
+
+`TEX'
+ The path to TeX. The default is `tex'
+
+`MSGFMT'
+ The path to msgfmt. The default is `msgfmt'
+
+`RCOPY'
+ The path to your copy command (GNU cp). The default is dependent
+ on whether or not SYMLINK is set (`t').
+
+ If SYMLINK is unset (blank), RCOPY's default is `cp -af'. If
+ SYMLINK is set (`t'), RCOPY's default is `cp --force --recursive
+ --symbolic-link'.
+
+ It should be noted that in most cases the defaults should be fine.
+Most people will probably only need to alter:
+
+ * XEMACS_INSTALLED_PACKAGES_ROOT
+
+ * NONMULE_INSTALLED_PACKAGES_ROOT
+
+ * MULE_INSTALLED_PACKAGES_ROOT
+
+ * NONMULE_PACKAGES
+
+ * MULE_PACKAGES
+
+\1f
+File: lispref.info, Node: Creating Packages, Next: Documenting Packages, Prev: Local.rules File, Up: Packaging
+
+Creating Packages:
+******************
+
+Creating a package from an existing Lisp library is not very difficult.
+
+ In addition to the Lisp libraries themselves, you need a *Note
+package-info.in:: file and a simple *Note Makefile::. The rest is done
+by `XEmacs.rules', part of the packaging system infrastructure.
+
+* Menu:
+
+* package-info.in:: package-info.in
+* Makefile:: `Makefile'
+
+\1f
+File: lispref.info, Node: package-info.in, Next: Makefile, Up: Creating Packages
+
+package-info.in
+***************
+
+`package-info.in' contains information that gets injected into the
+`package-index' file when `make bindist' is run. Here is a real world
+example from the xemacs-base package (a description of each field
+follows the example):
+
+ (xemacs-base
+ (standards-version 1.1
+ version VERSION
+ author-version AUTHOR_VERSION
+ date DATE
+ build-date BUILD_DATE
+ maintainer MAINTAINER
+ distribution xemacs
+ priority high
+ category CATEGORY
+ dump nil
+ description "Fundamental XEmacs support, you almost certainly need this."
+ filename FILENAME
+ md5sum MD5SUM
+ size SIZE
+ provides (add-log advice-preload advice annotations assoc case-table chistory comint-xemacs comint compile debug ebuff-menu echistory edmacro ehelp electric enriched env facemenu ffap helper imenu iso-syntax macros novice outline passwd pp regexp-opt regi ring shell skeleton sort thing time-stamp timezone tq xbm-button xpm-button)
+ requires (REQUIRES)
+ type regular
+ ))
+
+Description of the Fields in `package-info.in':
+-----------------------------------------------
+
+`NAME'
+ The name of the package. In the case of the example it is
+ `xemacs-base'.
+
+`standards-version'
+ Part of the internal package infrastructure, its value should
+ always be `1.1'. Do not change this.
+
+`version'
+ This is the XEmacs package version number of the package. It is
+ set from the `Makefile' variable VERSION. This is something that
+ the XEmacs Package Release Engineer deals with so there is no need
+ for a package maintainer to touch it. In `package-info.in' just
+ put the place-marker, `VERSION' here.
+
+`author-version'
+ This is the package's internal, or `upstream' version number if it
+ has one. It is set from the `Makefile' variable AUTHOR_VERSION.
+
+`date'
+ This is the date of the last change made to the package. It is
+ auto-generated at build time, taken from the package's toplevel
+ `ChangeLog'.
+
+`build-date'
+ The date the package was built. It is auto-generated.
+
+`maintainer'
+ This is the name and email address of the package's maintainer.
+ It is taken from the `Makefile' variable MAINTAINER.
+
+`distribution'
+ An unused field, leave as `xemacs'
+
+`priority'
+ An unused field, can be any of `high', `medium', or `low'.
+
+`category'
+ The `category' of the package. It is taken from the `Makefile'
+ variable CATEGORY and can be either `standard' for non-Mule
+ packages, or `mule' for Mule packages. The is also provision for
+ `unsupported' in this field which would be for packages that
+ XEmacs.org do not distribute.
+
+ *N.B.* As yet, the XEmacs Packaging System does _not_ support this
+ type of package. It will in the future.
+
+`dump'
+ Unused. Always `nil'
+
+`description'
+ A free form short description of the package.
+
+`filename'
+ The file name of the package's binary tarball. It is generated at
+ build time by `make bindist'.
+
+`md5sum'
+ The MD5 message digest of the package's binary tarball. Generated
+ at build time by `make bindist'.
+
+`size'
+ The size in bytes of the package's binary tarball. Generated at
+ build time.
+
+`provides'
+ A whitespace separated list of _all_ the features the package
+ provides. Surround the list with parens.
+
+`requires'
+ Taken from the `Makefile' variable REQUIRES. It is a list of all
+ the package's dependencies, including any macros and defstructs
+ that need to be inlined.
+
+ `REQUIRES' cannot be correctly computed from the calls to
+ `require' in the package's library sources. `REQUIRES' is used to
+ ensure that all macro and defstruct definitions used by the
+ package are available at build time. This is not merely a matter
+ of efficiency, to get the expansions inlined. In fact, it is
+ _impossible_ to call a macro by name in byte-compiled Emacs Lisp
+ code. Thus, if the macro expansion is not inlined, the call will
+ result in an error at run-time! Thus, packages providing
+ libraries that would be loaded because of autoload definitions
+ must also be included.
+
+`type'
+ Can either be `regular' for a regular package, or `single-file'
+ for a single file package.
+
+ *N.B.* This doesn't refer to the number of lisp files in a
+ package. A single-file package can have multiple lisp files in it.
+ *Note Package Terminology::.
+
+ The fields in `package-info.in' that need to be changed directly are:
+
+ * NAME
+
+ * description
+
+ * provides
+
+ * type
+
+ Everything else is either set from the appropriate `Makefile'
+variable, is auto-generated at build time, or is static.
+
+\1f
+File: lispref.info, Node: Makefile, Prev: package-info.in, Up: Creating Packages
+
+`Makefile'
+**********
+
+The `Makefile' is quite stylized. The idea is similar to an
+`Imakefile' or an `automake' file: the complexity is hidden in generic
+rules files, in this case the `XEmacs.rules' include file in the top
+directory of the packages hierarchy.
+
+ It is important to note that the XEmacs used to compile packages is
+the bare minimum: it is called with the `-no-autoloads'. This means
+that anything not dumped into XEmacs by default needs to be specified
+in the `REQUIRES' variable (for packaged Lisp) or in some cases the
+`PRELOADS' (autoloads used in libraries mentioned in `PRELOADS').
+
+ There isn't much to an XEmacs Packaging System `Makefile', basically
+it just contains a few `Makefile' variables and that's it. See the
+example.
+
+ Here is a real world example, from the `build' package:
+
+ # Makefile for build lisp code
+
+ # This file is part of XEmacs.
+
+ # XEmacs 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, or (at your option) any
+ # later version.
+
+ # XEmacs 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 XEmacs; see the file COPYING. If not, write to
+ # the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ # Boston, MA 02111-1307, USA.
+
+ # For the time being, remove MULE_ELCS from the all dependencies if
+ # building without Mule.
+
+ VERSION = 1.10
+ AUTHOR_VERSION = 2.02
+ MAINTAINER = Adrian Aichner <adrian@xemacs.org>
+ PACKAGE = build
+ PKG_TYPE = regular
+ REQUIRES = xemacs-base pcl-cvs dired w3 prog-modes
+ CATEGORY = standard
+
+ ELCS = build.elc build-report.elc
+
+ STANDARD_DOCS = t
+
+ include ../../XEmacs.rules
+
+ Most packages don't need any more than what you see above. It is
+usually _not_ necessary to specify any special `Makefile' rules.
+Everything is handled from the `*.rules' files in the toplevel of the
+package source hierarchy.
+
+ Of course, with that said, there are always exceptions to the rule.
+If you think that your package will need some special `Makefile'
+hackery contact the XEmacs developers <xemacs-beta@xemacs.org>. We
+distribute over 100 packages so the chances are good that you won't be
+the first to need such hackery and it is probably already catered for.
+
+`Makefile' Variables Explained:
+-------------------------------
+
+A number of `make' variables are defined by the XEmacs Packaging
+System. Some are required, others are optional. Of course your
+`Makefile' may define other variables for private use, but you should
+be careful not to choose names that conflict with variables defined and
+used by the XEmacs Packaging System.
+
+ The required variables are described in the table below. The
+corresponding field names for `package-info.in', where relevant, are
+given in parentheses.
+
+`VERSION'
+ (version) The version of the XEmacs package, a numeric literal (a
+ decimal fixed-point number with two-places of precision). The
+ only person who ever needs to touch this is the XEmacs Packages
+ Release Engineer.
+
+`AUTHOR_VERSION'
+ (author-version) The upstream author's version, an uninterpreted
+ literal.
+
+`MAINTAINER'
+ (maintainer) A literal containing the XEmacs package's maintainer
+ and his/her email address.
+
+`PACKAGE'
+ The name of the package, a literal
+
+`PKG_TYPE'
+ The type of package, a literal containing either `regular' for
+ regular packages, or `single-file' for single-file packages. This
+ should feed the `type' field in `package-info.in', but currently
+ it doesn't.
+
+ *N.B.* `single-file' here does _not_ refer to the number of lisp
+ files in a package. *Note Package Terminology::.
+
+`CATEGORY'
+ (category) A literal, either `standard' or `mule'. The non-Mule
+ packages are `standard' and the Mule packages are, you guessed it,
+ `mule'. This field is used at package installation time as part of
+ the process of determining where a package should be installed to.
+
+`REQUIRES'
+ (requires) A list of packages required to correctly build this
+ package.
+
+ Note that the usual form in `package-info.in' already has the
+ parentheses, so the `make' variable should be set to a
+ space-separated list of package names _not_ enclosed in
+ parentheses.
+
+ The list is of _packages_, not _libraries_, as would ordinarily be
+ provided to the Lisp `require' function.
+
+ `REQUIRES' cannot be correctly computed from the calls to
+ `require' in the package's library sources. `REQUIRES' is used to
+ ensure that all macro and defstruct definitions used by the
+ package are available at build time. This is not merely a matter
+ of efficiency, to get the expansions inlined. In fact, it is
+ _impossible_ to call a macro by name in byte-compiled Emacs Lisp
+ code. Thus, if the macro expansion is not inlined, the call will
+ result in an error at run-time! Thus, packages providing
+ libraries that would be loaded because of autoload definitions
+ must also be included.
+
+`ELCS'
+ The list of the byte-compiled Lisp files used by the package.
+ These files and their `.el' versions will be included in the binary
+ package. This variable determines which libraries will be
+ byte-compiled. These libraries are also deleted by `make clean'.
+
+ Note there is no sanity-checking done on this variable. If you put
+ `.el' files in here, they will not be compiled and they _will_ be
+ deleted by `make clean'. You would surely be very distressed if
+ that happened, so be very careful. If this variable is left
+ empty, none of your Lisp code will be compiled or packaged. This
+ would be a less than amusing surprise, too.
+
+ We don't consider this a feature, of course. Please do submit
+ code to do sanity checking to <xemacs-patches@xemacs.org>.
+
+ Optional, but commonly used variables are explained below.
+
+`ELCS_1'
+ A list of extra byte-compiled Lisp files used by the package to be
+ installed in a subdirectory of the package's lisp directory. The
+ same care should be taken with this as with ELCS in regard to
+ `make clean'.
+
+`ELCS_1_DEST'
+ The name of the subdirectory for the ELCS_1 files to be installed
+ to. Be sure to include `$(PACKAGE)/' as part of the name.
+
+ ELCS_1_DEST = $(PACKAGE)/extra
+
+ Would put the ELCS_1 files for the package, `foo' into
+ `xemacs-packages/lisp/foo/extra/'.
+
+`EARLY_GENERATED_LISP'
+ For additional `.el' files that will be generated before any
+ byte-compiling happens. Use this for `autoload-type' files. You
+ must write `Makefile' rules to build these files.
+
+`GENERATED_LISP'
+ For additional `.el' files that will be generated at
+ byte-compilation time. You must write `Makefile' rules to build
+ these files.
+
+`PRELOADS'
+ This is used if you need to pass extra command line arguments to
+ XEmacs to build the package. For instance, a specification for
+ loading libraries containing macros before compiling the Lisp in
+ the package. This is spliced directly into the invocation of
+ XEmacs for byte-compilation, so it must contain the `-l' flag for
+ XEmacs:
+
+ PRELOADS=-l ./apackage-macros.el -l ../bpackage/lisp/bpackage-macros.el
+
+ Preloads are loaded before `package-compile.el', so the LOAD-PATH
+ is minimal. Therefore `PRELOADS' must specify a full path to
+ packaged Lisp. The base LOAD-PATH does include the core Lisp
+ directory, so core libraries are found.
+
+`AUTOLOAD_PATH'
+ The subdirectory in the package's source tree where the `.el' files
+ reside. This is where the `auto-autoloads.el' file will be placed.
+
+ *N.B.* There is no need to use this variable if the `.el' files
+ are in the package's toplevel directory. AUTOLOAD_PATH defaults
+ to `.'.
+
+`PACKAGE_SUPPRESS'
+ Place calls to `package-suppress' here to indicate Lisp libraries
+ that should only be available to particular versions of XEmacs.
+ For example:
+
+ PACKAGE_SUPPRESS = \
+ (package-suppress 'xemacs-base \"regexp-opt\" '(emacs-version>= 21 5 11)) \
+ (package-suppress 'xemacs-base \"easy-mmode\" '(emacs-version>= 21 5 11))
+
+ *N.B.* This feature has not yet been implemented in XEmacs yet.
+ It will appear in an upcoming version of XEmacs 21.5.
+
+`STANDARD_DOCS'
+ Set this to `t' if your package's Texinfo source file is located in
+ the package's toplevel directory _and_ is named `$(PACKAGE).texi'.
+
+`EXPLICIT_DOCS'
+ Use this to explicitly list Texinfo sources that _aren't_ in the
+ package's toplevel directory. For example:
+
+ EXPLICIT_DOCS = texi/$(PACKAGE).texi
+
+ See DOCS_TXI_EXTENSION and DOCS_TEXINFO_EXTENSION if you don't use
+ the `.texi' file extension on your Texinfo sources.
+
+`EXTRA_TEXI_FILES'
+ List here extra Texinfo source files needed to build your
+ documentation. Whatever is listed here is passed on to `makeinfo'
+ as a dependency.
+
+`EXTRA_HTML_FILES'
+ Use this to specify extra `.html' files to output.
+
+`DOCS_TEXINFO_EXTENSION'
+ Set this to `t' if your Texinfo source files have a `.texinfo'
+ extension.
+
+`DOCS_TXI_EXTENSION'
+ Set this to `t' if your Texinfo source files have a `.txi'
+ extension.
+
+`EXTRA_DOC_FILES'
+ Files listed here will be installed to `.../man/$(PACKAGE)/'. For
+ example, you might want to list TeX files or `.eps' files here.
+
+`EXTRA_SOURCES'
+ Other files (such as extra Lisp sources or an upstream `Makefile')
+ that are normally placed in the installed Lisp directory, but not
+ byte-compiled. These files are _preserved_ by the `clean' targets.
+
+`LIBSRC_FILES'
+ For files that need to be installed to `lib-src/$(PACKAGE)/'. If
+ the files listed here need to be built you will have to write
+ `Makefile' rules to do so.
+
+`DATA_FILES'
+ Any data files, such as pixmaps, READMEs, and ChangeLogs. These
+ must be paths relative to the root of the package's source tree.
+ These files will be copied to `$(DATA_DEST)' for installation.
+ Any directory component of the path for a file will be stripped,
+ so that the file ends up in `$(DATA_DEST)', not in a subdiredtory.
+
+`DATA_DEST'
+ The directory where the files in DATA_FILES are installed to. It
+ is a subdirectory of the installed `etc/' directory. Be sure to
+ prefix this value with `$(PACKAGE)', for example:
+
+ DATA_DEST = $(PACKAGE)/foo
+
+ Would put files into `.../etc/$(PACKAGE)/foo/'.
+
+`DATA_1_FILES ... DATA_35_FILES'
+ For data files that need to go into a different directory from
+ DATA_DEST.
+
+`DATA_1_DEST ... DATA_35_DEST'
+ The name of the subdirectory for files specified in DATA_N_FILES.
+ And like DATA_DEST, be sure to prefix `$(PACKAGE)' to the value of
+ these variables.
+
+`EXTRA_DEPENDENCIES'
+ For additional files to build that aren't appropriate to place in
+ any other `Makefile' variable. You will need to write `Makefile'
+ rules to build these files.
+
+`package-compile.el'
+====================
+
+The XEmacs Packaging System does not automatically become aware of your
+package simply because there is a new subtree. If any package,
+including your own, requires any of your files, it must be explicitly
+added to the compile environment or loads/requires that search
+load-path will fail. The changes that need to be made are
+
+*an entry in `package-directory-map'*
+ This tells the XEmacs Packaging System which distribution
+ (currently `xemacs-packages' or `mule-packages') your package is
+ found in. It then looks in the distribution subdirectory whose
+ name is the same as the package's.
+
+*an entry in the `cond' in `package-name-to-directory'*
+ This is optional; it is necessary only if you keep your Lisp code
+ somewhere other than the top-level directory of the package's
+ source tree, eg, in `packages/xemacs-packages/PACKAGE/lisp'.
+
+ This only needs to be done once, when the package is first added to
+the XEmacs Packaging System. (Well, when you randomly change the
+subdirectory layout, too.) Your changes to `package-compile.el' must
+be cleared and checked in by the XEmacs Package Release Engineer before
+your package will build correctly from a fresh checkout.
+
+ This is unfortunate; it works pretty well once set up, but can cause
+confusion when first building a package in the XEmacs Packaging System
+context. In particular, if the `package-directory-map' entry for a
+required package, including the package itself, is not found, the
+necessary requires will not be executed by `package-compile.el'. If
+required functions are executed (under `eval-when-compile'), they won't
+be found and the compile will fail. If required function is actually a
+macro, the byte compiler will not recognize that, compile a function
+call to the macro. This will cause a run-time error because the
+byte-code interpreter does not know how to execute macros. (Macros can
+always be expanded at compile-time, and this is more efficient.)
+
+ If your package keeps some or all Lisp code somewhere other than the
+top directory, then an entry in `package-name-to-directory' is also
+necessary, or requires will fail, leading to the problems just
+described.
+
+\1f
+File: lispref.info, Node: Documenting Packages, Next: Issues, Prev: Creating Packages, Up: Packaging
+
+Documenting Packages:
+=====================
+
+Some random notes on documenting your package.
+
+ Do write a Texinfo file. It's not that hard to do basically, and
+even using the more advanced features of Texinfo soon become natural.
+For a start, just grab the template `Samples/package.texi' from the
+XEmacs Packaging System source tree, and drop your current README into
+the Top node. At least this way your documentation will be accessible
+from the standard Info readers. Next, try to add lots of
+cross-referencing and logical markup, and then node structure.
+
+ Address both end users and developer issues. You may not be the
+maintainer forever.
+
+ If you are maintaining a package that is part of the GNU Emacs
+distribution, you'll likely find that you occasionally synchronize your
+package with the GNU Emacs sources. When you synch a file,
+conventionally you should place a comment just above the standard `;;;
+Code' comment that looks like this:
+
+ ;; Synched with:
+ ;; GNU Emacs 21.1, 2002-02-08, Stephen Turnbull <stephen@xemacs.org>
+
+ This comment is a status flag; the ChangeLog doesn't really give the
+same information.
+
+ Do maintain a detailed ChangeLog.
+
+\1f
+File: lispref.info, Node: Issues, Prev: Documenting Packages, Up: Packaging
+
+Issues
+======
+
+To be completed.
+
+\1f
+File: lispref.info, Node: Lisp Data Types, Next: Numbers, Prev: Packaging, 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.
+
+\1f
+File: lispref.info, Node: Character Type, Next: Symbol Type, Prev: Floating Point Type, Up: Programming Types
+
+Character Type
+--------------
+
+In XEmacs version 19, and in all versions of FSF GNU Emacs, a
+"character" in XEmacs Lisp is nothing more than an integer. This is
+yet another holdover from XEmacs Lisp's derivation from vintage-1980
+Lisps; modern versions of Lisp consider this equivalence a bad idea,
+and have separate character types. In XEmacs version 20, the modern
+convention is followed, and characters are their own primitive types.
+(This change was necessary in order for MULE, i.e. Asian-language,
+support to be correctly implemented.)
+
+ Even in XEmacs version 20, remnants of the equivalence between
+characters and integers still exist; this is termed the "char-int
+confoundance disease". In particular, many functions such as `eq',
+`equal', and `memq' have equivalent functions (`old-eq', `old-equal',
+`old-memq', etc.) that pretend like characters are integers are the
+same. Byte code compiled under any version 19 Emacs will have all such
+functions mapped to their `old-' equivalents when the byte code is read
+into XEmacs 20. This is to preserve compatibility--Emacs 19 converts
+all constant characters to the equivalent integer during
+byte-compilation, and thus there is no other way to preserve byte-code
+compatibility even if the code has specifically been written with the
+distinction between characters and integers in mind.
+
+ Every character has an equivalent integer, called the "character
+code". For example, the character `A' is represented as the
+integer 65, following the standard ASCII representation of characters.
+If XEmacs was not compiled with MULE support, the range of this integer
+will always be 0 to 255--eight bits, or one byte. (Integers outside
+this range are accepted but silently truncated; however, you should
+most decidedly _not_ rely on this, because it will not work under
+XEmacs with MULE support.) When MULE support is present, the range of
+character codes is much larger. (Currently, 19 bits are used.)
+
+ FSF GNU Emacs uses kludgy character codes above 255 to represent
+keyboard input of ASCII characters in combination with certain
+modifiers. XEmacs does not use this (a more general mechanism is used
+that does not distinguish between ASCII keys and other keys), so you
+will never find character codes above 255 in a non-MULE XEmacs.
+
+ Individual characters are not often used in programs. It is far more
+common to work with _strings_, which are sequences composed of
+characters. *Note String Type::.
+
+ The read syntax for characters begins with a question mark, followed
+by the character (if it's printable) or some symbolic representation of
+it. In XEmacs 20, where characters are their own type, this is also the
+print representation. In XEmacs 19, however, where characters are
+really integers, the printed representation of a character is a decimal
+number. This is also a possible read syntax for a character, but
+writing characters that way in Lisp programs is a very bad idea. You
+should _always_ use the special read syntax formats that XEmacs Lisp
+provides for characters.
+
+ The usual read syntax for alphanumeric characters is a question mark
+followed by the character; thus, `?A' for the character `A', `?B' for
+the character `B', and `?a' for the character `a'.
+
+ For example:
+
+ ;; Under XEmacs 20:
+ ?Q => ?Q ?q => ?q
+ (char-int ?Q) => 81
+ ;; Under XEmacs 19:
+ ?Q => 81 ?q => 113
+
+ You can use the same syntax for punctuation characters, but it is
+often a good idea to add a `\' so that the Emacs commands for editing
+Lisp code don't get confused. For example, `?\ ' is the way to write
+the space character. If the character is `\', you _must_ use a second
+`\' to quote it: `?\\'. XEmacs 20 always prints punctuation characters
+with a `\' in front of them, to avoid confusion.
+
+ You can express the characters Control-g, backspace, tab, newline,
+vertical tab, formfeed, return, and escape as `?\a', `?\b', `?\t',
+`?\n', `?\v', `?\f', `?\r', `?\e', respectively. Their character codes
+are 7, 8, 9, 10, 11, 12, 13, and 27 in decimal. Thus,
+
+ ;; Under XEmacs 20:
+ ?\a => ?\^G ; `C-g'
+ (char-int ?\a) => 7
+ ?\b => ?\^H ; backspace, <BS>, `C-h'
+ (char-int ?\b) => 8
+ ?\t => ?\t ; tab, <TAB>, `C-i'
+ (char-int ?\t) => 9
+ ?\n => ?\n ; newline, <LFD>, `C-j'
+ ?\v => ?\^K ; vertical tab, `C-k'
+ ?\f => ?\^L ; formfeed character, `C-l'
+ ?\r => ?\r ; carriage return, <RET>, `C-m'
+ ?\e => ?\^[ ; escape character, <ESC>, `C-['
+ ?\\ => ?\\ ; backslash character, `\'
+ ;; Under XEmacs 19:
+ ?\a => 7 ; `C-g'
+ ?\b => 8 ; backspace, <BS>, `C-h'
+ ?\t => 9 ; tab, <TAB>, `C-i'
+ ?\n => 10 ; newline, <LFD>, `C-j'
+ ?\v => 11 ; vertical tab, `C-k'
+ ?\f => 12 ; formfeed character, `C-l'
+ ?\r => 13 ; carriage return, <RET>, `C-m'
+ ?\e => 27 ; escape character, <ESC>, `C-['
+ ?\\ => 92 ; backslash character, `\'
+
+ These sequences which start with backslash are also known as "escape
+sequences", because backslash plays the role of an escape character;
+this usage has nothing to do with the character <ESC>.
+
+ Control characters may be represented using yet another read syntax.
+This consists of a question mark followed by a backslash, caret, and the
+corresponding non-control character, in either upper or lower case. For
+example, both `?\^I' and `?\^i' are valid read syntax for the character
+`C-i', the character whose value is 9.
+
+ Instead of the `^', you can use `C-'; thus, `?\C-i' is equivalent to
+`?\^I' and to `?\^i':
+
+ ;; Under XEmacs 20:
+ ?\^I => ?\t ?\C-I => ?\t
+ (char-int ?\^I) => 9
+ ;; Under XEmacs 19:
+ ?\^I => 9 ?\C-I => 9
+
+ There is also a character read syntax beginning with `\M-'. This
+sets the high bit of the character code (same as adding 128 to the
+character code). For example, `?\M-A' stands for the character with
+character code 193, or 128 plus 65. You should _not_ use this syntax
+in your programs. It is a holdover of yet another confoundance disease
+from earlier Emacsen. (This was used to represent keyboard input with
+the <META> key set, thus the `M'; however, it conflicts with the
+legitimate ISO-8859-1 interpretation of the character code. For
+example, character code 193 is a lowercase `a' with an acute accent, in
+ISO-8859-1.)
+
+ Finally, the most general read syntax consists of a question mark
+followed by a backslash and the character code in octal (up to three
+octal digits); thus, `?\101' for the character `A', `?\001' for the
+character `C-a', and `?\002' for the character `C-b'. Although this
+syntax can represent any ASCII character, it is preferred only when the
+precise octal value is more important than the ASCII representation.
+
+ ;; Under XEmacs 20:
+ ?\012 => ?\n ?\n => ?\n ?\C-j => ?\n
+ ?\101 => ?A ?A => ?A
+ ;; Under XEmacs 19:
+ ?\012 => 10 ?\n => 10 ?\C-j => 10
+ ?\101 => 65 ?A => 65
+
+ A backslash is allowed, and harmless, preceding any character without
+a special escape meaning; thus, `?\+' is equivalent to `?+'. There is
+no reason to add a backslash before most characters. However, you
+should add a backslash before any of the characters `()\|;'`"#.,' to
+avoid confusing the Emacs commands for editing Lisp code. Also add a
+backslash before whitespace characters such as space, tab, newline and
+formfeed. However, it is cleaner to use one of the easily readable
+escape sequences, such as `\t', instead of an actual whitespace
+character such as a tab.
+
+\1f
+File: lispref.info, Node: Symbol Type, Next: Sequence Type, Prev: Character Type, Up: Programming Types
+
+Symbol Type
+-----------
+
+A "symbol" in XEmacs Lisp is an object with a name. The symbol name
+serves as the printed representation of the symbol. In ordinary use,
+the name is unique--no two symbols have the same name.
+
+ A symbol can serve as a variable, as a function name, or to hold a
+property list. Or it may serve only to be distinct from all other Lisp
+objects, so that its presence in a data structure may be recognized
+reliably. In a given context, usually only one of these uses is
+intended. But you can use one symbol in all of these ways,
+independently.
+
+ A symbol name can contain any characters whatever. Most symbol names
+are written with letters, digits, and the punctuation characters
+`-+=*/'. Such names require no special punctuation; the characters of
+the name suffice as long as the name does not look like a number. (If
+it does, write a `\' at the beginning of the name to force
+interpretation as a symbol.) The characters `_~!@$%^&:<>{}' are less
+often used but also require no special punctuation. Any other
+characters may be included in a symbol's name by escaping them with a
+backslash. In contrast to its use in strings, however, a backslash in
+the name of a symbol simply quotes the single character that follows the
+backslash. For example, in a string, `\t' represents a tab character;
+in the name of a symbol, however, `\t' merely quotes the letter `t'.
+To have a symbol with a tab character in its name, you must actually
+use a tab (preceded with a backslash). But it's rare to do such a
+thing.
+
+ Common Lisp note: In Common Lisp, lower case letters are always
+ "folded" to upper case, unless they are explicitly escaped. In
+ Emacs Lisp, upper case and lower case letters are distinct.
+
+ Here are several examples of symbol names. Note that the `+' in the
+fifth example is escaped to prevent it from being read as a number.
+This is not necessary in the sixth example because the rest of the name
+makes it invalid as a number.
+
+ foo ; A symbol named `foo'.
+ FOO ; A symbol named `FOO', different from `foo'.
+ char-to-string ; A symbol named `char-to-string'.
+ 1+ ; A symbol named `1+'
+ ; (not `+1', which is an integer).
+ \+1 ; A symbol named `+1'
+ ; (not a very readable name).
+ \(*\ 1\ 2\) ; A symbol named `(* 1 2)' (a worse name).
+ +-*/_~!@$%^&=:<>{} ; A symbol named `+-*/_~!@$%^&=:<>{}'.
+ ; These characters need not be escaped.
+
+\1f
+File: lispref.info, Node: Sequence Type, Next: Cons Cell Type, Prev: Symbol Type, Up: Programming Types
+
+Sequence Types
+--------------
+
+A "sequence" is a Lisp object that represents an ordered set of
+elements. There are two kinds of sequence in XEmacs Lisp, lists and
+arrays. Thus, an object of type list or of type array is also
+considered a sequence.
+
+ Arrays are further subdivided into strings, vectors, and bit vectors.
+Vectors can hold elements of any type, but string elements must be
+characters, and bit vector elements must be either 0 or 1. However, the
+characters in a string can have extents (*note Extents::) and text
+properties (*note Text Properties::) like characters in a buffer;
+vectors do not support extents or text properties even when their
+elements happen to be characters.
+
+ Lists, strings, vectors, and bit vectors are different, but they have
+important similarities. For example, all have a length L, and all have
+elements which can be indexed from zero to L minus one. Also, several
+functions, called sequence functions, accept any kind of sequence. For
+example, the function `elt' can be used to extract an element of a
+sequence, given its index. *Note Sequences Arrays Vectors::.
+
+ It is impossible to read the same sequence twice, since sequences are
+always created anew upon reading. If you read the read syntax for a
+sequence twice, you get two sequences with equal contents. There is one
+exception: the empty list `()' always stands for the same object, `nil'.
+
+\1f
+File: lispref.info, Node: Cons Cell Type, Next: Array Type, Prev: Sequence Type, Up: Programming Types
+
+Cons Cell and List Types
+------------------------
+
+A "cons cell" is an object comprising two pointers named the CAR and
+the CDR. Each of them can point to any Lisp object.
+
+ A "list" is a series of cons cells, linked together so that the CDR
+of each cons cell points either to another cons cell or to the empty
+list. *Note Lists::, for functions that work on lists. Because most
+cons cells are used as part of lists, the phrase "list structure" has
+come to refer to any structure made out of cons cells.
+
+ The names CAR and CDR have only historical meaning now. The
+original Lisp implementation ran on an IBM 704 computer which divided
+words into two parts, called the "address" part and the "decrement";
+CAR was an instruction to extract the contents of the address part of a
+register, and CDR an instruction to extract the contents of the
+decrement. By contrast, "cons cells" are named for the function `cons'
+that creates them, which in turn is named for its purpose, the
+construction of cells.
+
+ Because cons cells are so central to Lisp, we also have a word for
+"an object which is not a cons cell". These objects are called "atoms".
+
+ The read syntax and printed representation for lists are identical,
+and consist of a left parenthesis, an arbitrary number of elements, and
+a right parenthesis.
+
+ Upon reading, each object inside the parentheses becomes an element
+of the list. That is, a cons cell is made for each element. The CAR
+of the cons cell points to the element, and its CDR points to the next
+cons cell of the list, which holds the next element in the list. The
+CDR of the last cons cell is set to point to `nil'.
+
+ A list can be illustrated by a diagram in which the cons cells are
+shown as pairs of boxes. (The Lisp reader cannot read such an
+illustration; unlike the textual notation, which can be understood by
+both humans and computers, the box illustrations can be understood only
+by humans.) The following represents the three-element list `(rose
+violet buttercup)':
+
+ ___ ___ ___ ___ ___ ___
+ |___|___|--> |___|___|--> |___|___|--> nil
+ | | |
+ | | |
+ --> rose --> violet --> buttercup
+
+ In this diagram, each box represents a slot that can refer to any
+Lisp object. Each pair of boxes represents a cons cell. Each arrow is
+a reference to a Lisp object, either an atom or another cons cell.
+
+ In this example, the first box, the CAR of the first cons cell,
+refers to or "contains" `rose' (a symbol). The second box, the CDR of
+the first cons cell, refers to the next pair of boxes, the second cons
+cell. The CAR of the second cons cell refers to `violet' and the CDR
+refers to the third cons cell. The CDR of the third (and last) cons
+cell refers to `nil'.
+
+ Here is another diagram of the same list, `(rose violet buttercup)',
+sketched in a different manner:
+
+ --------------- ---------------- -------------------
+ | car | cdr | | car | cdr | | car | cdr |
+ | rose | o-------->| violet | o-------->| buttercup | nil |
+ | | | | | | | | |
+ --------------- ---------------- -------------------
+
+ A list with no elements in it is the "empty list"; it is identical
+to the symbol `nil'. In other words, `nil' is both a symbol and a list.
+
+ Here are examples of lists written in Lisp syntax:
+
+ (A 2 "A") ; A list of three elements.
+ () ; A list of no elements (the empty list).
+ nil ; A list of no elements (the empty list).
+ ("A ()") ; A list of one element: the string `"A ()"'.
+ (A ()) ; A list of two elements: `A' and the empty list.
+ (A nil) ; Equivalent to the previous.
+ ((A B C)) ; A list of one element
+ ; (which is a list of three elements).
+
+ Here is the list `(A ())', or equivalently `(A nil)', depicted with
+boxes and arrows:
+
+ ___ ___ ___ ___
+ |___|___|--> |___|___|--> nil
+ | |
+ | |
+ --> A --> nil
+
+* Menu:
+
+* Dotted Pair Notation:: An alternative syntax for lists.
+* Association List Type:: A specially constructed list.
+
+\1f
+File: lispref.info, Node: Dotted Pair Notation, Next: Association List Type, Up: Cons Cell Type
+
+Dotted Pair Notation
+....................
+
+"Dotted pair notation" is an alternative syntax for cons cells that
+represents the CAR and CDR explicitly. In this syntax, `(A . B)'
+stands for a cons cell whose CAR is the object A, and whose CDR is the
+object B. Dotted pair notation is therefore more general than list
+syntax. In the dotted pair notation, the list `(1 2 3)' is written as
+`(1 . (2 . (3 . nil)))'. For `nil'-terminated lists, the two
+notations produce the same result, but list notation is usually clearer
+and more convenient when it is applicable. When printing a list, the
+dotted pair notation is only used if the CDR of a cell is not a list.
+
+ Here's how box notation can illustrate dotted pairs. This example
+shows the pair `(rose . violet)':
+
+ ___ ___
+ |___|___|--> violet
+ |
+ |
+ --> rose
+
+ Dotted pair notation can be combined with list notation to represent
+a chain of cons cells with a non-`nil' final CDR. For example, `(rose
+violet . buttercup)' is equivalent to `(rose . (violet . buttercup))'.
+The object looks like this:
+
+ ___ ___ ___ ___
+ |___|___|--> |___|___|--> buttercup
+ | |
+ | |
+ --> rose --> violet
+
+ These diagrams make it evident why `(rose . violet . buttercup)' is
+invalid syntax; it would require a cons cell that has three parts
+rather than two.
+
+ The list `(rose violet)' is equivalent to `(rose . (violet))' and
+looks like this:
+
+ ___ ___ ___ ___
+ |___|___|--> |___|___|--> nil
+ | |
+ | |
+ --> rose --> violet
+
+ Similarly, the three-element list `(rose violet buttercup)' is
+equivalent to `(rose . (violet . (buttercup)))'. It looks like this:
+
+ ___ ___ ___ ___ ___ ___
+ |___|___|--> |___|___|--> |___|___|--> nil
+ | | |
+ | | |
+ --> rose --> violet --> buttercup
+
+\1f
+File: lispref.info, Node: Association List Type, Prev: Dotted Pair Notation, Up: Cons Cell Type
+
+Association List Type
+.....................
+
+An "association list" or "alist" is a specially-constructed list whose
+elements are cons cells. In each element, the CAR is considered a
+"key", and the CDR is considered an "associated value". (In some
+cases, the associated value is stored in the CAR of the CDR.)
+Association lists are often used as stacks, since it is easy to add or
+remove associations at the front of the list.
+
+ For example,
+
+ (setq alist-of-colors
+ '((rose . red) (lily . white) (buttercup . yellow)))
+
+sets the variable `alist-of-colors' to an alist of three elements. In
+the first element, `rose' is the key and `red' is the value.
+
+ *Note Association Lists::, for a further explanation of alists and
+for functions that work on alists.
+
+\1f
+File: lispref.info, Node: Array Type, Next: String Type, Prev: Cons Cell Type, Up: Programming Types
+
+Array Type
+----------
+
+An "array" is composed of an arbitrary number of slots for referring to
+other Lisp objects, arranged in a contiguous block of memory.
+Accessing any element of an array takes the same amount of time. In
+contrast, accessing an element of a list requires time proportional to
+the position of the element in the list. (Elements at the end of a
+list take longer to access than elements at the beginning of a list.)
+
+ XEmacs defines three types of array, strings, vectors, and bit
+vectors. A string is an array of characters, a vector is an array of
+arbitrary objects, and a bit vector is an array of 1's and 0's. All are
+one-dimensional. (Most other programming languages support
+multidimensional arrays, but they are not essential; you can get the
+same effect with an array of arrays.) Each type of array has its own
+read syntax; see *Note String Type::, *Note Vector Type::, and *Note
+Bit Vector Type::.
+
+ An array may have any length up to the largest integer; but once
+created, it has a fixed size. The first element of an array has index
+zero, the second element has index 1, and so on. This is called
+"zero-origin" indexing. For example, an array of four elements has
+indices 0, 1, 2, and 3.
+
+ The array type is contained in the sequence type and contains the
+string type, the vector type, and the bit vector type.
+
+\1f
+File: lispref.info, Node: String Type, Next: Vector Type, Prev: Array Type, Up: Programming Types
+
+String Type
+-----------
+
+A "string" is an array of characters. Strings are used for many
+purposes in XEmacs, as can be expected in a text editor; for example, as
+the names of Lisp symbols, as messages for the user, and to represent
+text extracted from buffers. Strings in Lisp are constants: evaluation
+of a string returns the same string.
+
+ The read syntax for strings is a double-quote, an arbitrary number of
+characters, and another double-quote, `"like this"'. The Lisp reader
+accepts the same formats for reading the characters of a string as it
+does for reading single characters (without the question mark that
+begins a character literal). You can enter a nonprinting character such
+as tab or `C-a' using the convenient escape sequences, like this: `"\t,
+\C-a"'. You can include a double-quote in a string by preceding it
+with a backslash; thus, `"\""' is a string containing just a single
+double-quote character. (*Note Character Type::, for a description of
+the read syntax for characters.)
+
+ The printed representation of a string consists of a double-quote,
+the characters it contains, and another double-quote. However, you must
+escape any backslash or double-quote characters in the string with a
+backslash, like this: `"this \" is an embedded quote"'.
+
+ The newline character is not special in the read syntax for strings;
+if you write a new line between the double-quotes, it becomes a
+character in the string. But an escaped newline--one that is preceded
+by `\'--does not become part of the string; i.e., the Lisp reader
+ignores an escaped newline while reading a string.
+
+ "It is useful to include newlines
+ in documentation strings,
+ but the newline is \
+ ignored if escaped."
+ => "It is useful to include newlines
+ in documentation strings,
+ but the newline is ignored if escaped."
+
+ A string can hold extents and properties of the text it contains, in
+addition to the characters themselves. This enables programs that copy
+text between strings and buffers to preserve the extents and properties
+with no special effort. *Note Extents::, *Note Text Properties::.
+
+ Note that FSF GNU Emacs has a special read and print syntax for
+strings with text properties, but XEmacs does not currently implement
+this. It was judged better not to include this in XEmacs because it
+entails that `equal' return `nil' when passed a string with text
+properties and the equivalent string without text properties, which is
+often counter-intuitive.
+
+ *Note Strings and Characters::, for functions that work on strings.
+
+\1f
+File: lispref.info, Node: Vector Type, Next: Bit Vector Type, Prev: String Type, Up: Programming Types
+
+Vector Type
+-----------
+
+A "vector" is a one-dimensional array of elements of any type. It
+takes a constant amount of time to access any element of a vector. (In
+a list, the access time of an element is proportional to the distance of
+the element from the beginning of the list.)
+
+ The printed representation of a vector consists of a left square
+bracket, the elements, and a right square bracket. This is also the
+read syntax. Like numbers and strings, vectors are considered constants
+for evaluation.
+
+ [1 "two" (three)] ; A vector of three elements.
+ => [1 "two" (three)]
+
+ *Note Vectors::, for functions that work with vectors.
+
+\1f
+File: lispref.info, Node: Bit Vector Type, Next: Function Type, Prev: Vector Type, Up: Programming Types
+
+Bit Vector Type
+---------------
+
+A "bit vector" is a one-dimensional array of 1's and 0's. It takes a
+constant amount of time to access any element of a bit vector, as for
+vectors. Bit vectors have an extremely compact internal representation
+(one machine bit per element), which makes them ideal for keeping track
+of unordered sets, large collections of boolean values, etc.
+
+ The printed representation of a bit vector consists of `#*' followed
+by the bits in the vector. This is also the read syntax. Like
+numbers, strings, and vectors, bit vectors are considered constants for
+evaluation.
+
+ #*00101000 ; A bit vector of eight elements.
+ => #*00101000
+
+ *Note Bit Vectors::, for functions that work with bit vectors.
+
+\1f
+File: lispref.info, Node: Function Type, Next: Macro Type, Prev: Bit Vector Type, Up: Programming Types
+
+Function Type
+-------------
+
+Just as functions in other programming languages are executable, "Lisp
+function" objects are pieces of executable code. However, functions in
+Lisp are primarily Lisp objects, and only secondarily the text which
+represents them. These Lisp objects are lambda expressions: lists
+whose first element is the symbol `lambda' (*note Lambda Expressions::).
+
+ In most programming languages, it is impossible to have a function
+without a name. In Lisp, a function has no intrinsic name. A lambda
+expression is also called an "anonymous function" (*note Anonymous
+Functions::). A named function in Lisp is actually a symbol with a
+valid function in its function cell (*note Defining Functions::).
+
+ Most of the time, functions are called when their names are written
+in Lisp expressions in Lisp programs. However, you can construct or
+obtain a function object at run time and then call it with the primitive
+functions `funcall' and `apply'. *Note Calling Functions::.
+
+\1f
+File: lispref.info, Node: Macro Type, Next: Primitive Function Type, Prev: Function Type, Up: Programming Types
+
+Macro Type
+----------
+
+A "Lisp macro" is a user-defined construct that extends the Lisp
+language. It is represented as an object much like a function, but with
+different parameter-passing semantics. A Lisp macro has the form of a
+list whose first element is the symbol `macro' and whose CDR is a Lisp
+function object, including the `lambda' symbol.
+
+ Lisp macro objects are usually defined with the built-in `defmacro'
+function, but any list that begins with `macro' is a macro as far as
+XEmacs is concerned. *Note Macros::, for an explanation of how to
+write a macro.
+
+\1f
+File: lispref.info, Node: Primitive Function Type, Next: Compiled-Function Type, Prev: Macro Type, Up: Programming Types
+
+Primitive Function Type
+-----------------------
+
+A "primitive function" is a function callable from Lisp but written in
+the C programming language. Primitive functions are also called
+"subrs" or "built-in functions". (The word "subr" is derived from
+"subroutine".) Most primitive functions evaluate all their arguments
+when they are called. A primitive function that does not evaluate all
+its arguments is called a "special form" (*note Special Forms::).
+
+ It does not matter to the caller of a function whether the function
+is primitive. However, this does matter if you try to substitute a
+function written in Lisp for a primitive of the same name. The reason
+is that the primitive function may be called directly from C code.
+Calls to the redefined function from Lisp will use the new definition,
+but calls from C code may still use the built-in definition.
+
+ The term "function" refers to all Emacs functions, whether written
+in Lisp or C. *Note Function Type::, for information about the
+functions written in Lisp.
+
+ Primitive functions have no read syntax and print in hash notation
+with the name of the subroutine.
+
+ (symbol-function 'car) ; Access the function cell
+ ; of the symbol.
+ => #<subr car>
+ (subrp (symbol-function 'car)) ; Is this a primitive function?
+ => t ; Yes.
+
+\1f
+File: lispref.info, Node: Compiled-Function Type, Next: Autoload Type, Prev: Primitive Function Type, Up: Programming Types
+
+Compiled-Function Type
+----------------------
+
+The byte compiler produces "compiled-function objects". The evaluator
+handles this data type specially when it appears as a function to be
+called. *Note Byte Compilation::, for information about the byte
+compiler.
+
+ The printed representation for a compiled-function object is normally
+`#<compiled-function...>'. If `print-readably' is true, however, it is
+`#[...]'.
+
+\1f
+File: lispref.info, Node: Autoload Type, Next: Char Table Type, Prev: Compiled-Function Type, Up: Programming Types
+
+Autoload Type
+-------------
+
+An "autoload object" is a list whose first element is the symbol
+`autoload'. It is stored as the function definition of a symbol as a
+placeholder for the real definition; it says that the real definition
+is found in a file of Lisp code that should be loaded when necessary.
+The autoload object contains the name of the file, plus some other
+information about the real definition.
+
+ After the file has been loaded, the symbol should have a new function
+definition that is not an autoload object. The new definition is then
+called as if it had been there to begin with. From the user's point of
+view, the function call works as expected, using the function definition
+in the loaded file.
+
+ An autoload object is usually created with the function `autoload',
+which stores the object in the function cell of a symbol. *Note
+Autoload::, for more details.
+
+\1f
+File: lispref.info, Node: Char Table Type, Next: Hash Table Type, Prev: Autoload Type, Up: Programming Types
+
+Char Table Type
+---------------
+
+(not yet documented)
+
+\1f
+File: lispref.info, Node: Hash Table Type, Next: Range Table Type, Prev: Char Table Type, Up: Programming Types
+
+Hash Table Type
+---------------
+
+A "hash table" is a table providing an arbitrary mapping from one Lisp
+object to another, using an internal indexing method called "hashing".
+Hash tables are very fast (much more efficient that using an
+association list, when there are a large number of elements in the
+table).
+
+ Hash tables have a special read syntax beginning with
+`#s(hash-table' (this is an example of "structure" read syntax. This
+notation is also used for printing when `print-readably' is `t'.
+
+ Otherwise they print in hash notation (The "hash" in "hash notation"
+has nothing to do with the "hash" in "hash table"), giving the number
+of elements, total space allocated for elements, and a unique number
+assigned at the time the hash table was created. (Hash tables
+automatically resize as necessary so there is no danger of running out
+of space for elements.)
+
+ (make-hash-table :size 50)
+ => #<hash-table 0/107 0x313a>
+
+ *Note Hash Tables::, for information on how to create and work with
+hash tables.
+
+\1f
+File: lispref.info, Node: Range Table Type, Next: Weak List Type, Prev: Hash Table Type, Up: Programming Types
+
+Range Table Type
+----------------
+
+A "range table" is a table that maps from ranges of integers to
+arbitrary Lisp objects. Range tables automatically combine overlapping
+ranges that map to the same Lisp object, and operations are provided
+for mapping over all of the ranges in a range table.
+
+ Range tables have a special read syntax beginning with
+`#s(range-table' (this is an example of "structure" read syntax, which
+is also used for char tables and faces).
+
+ (setq x (make-range-table))
+ (put-range-table 20 50 'foo x)
+ (put-range-table 100 200 "bar" x)
+ x
+ => #s(range-table data ((20 50) foo (100 200) "bar"))
+
+ *Note Range Tables::, for information on how to create and work with
+range tables.
+
+\1f
+File: lispref.info, Node: Weak List Type, Prev: Range Table Type, Up: Programming Types
+
+Weak List Type
+--------------
+
+(not yet documented)
+
+\1f
+File: lispref.info, Node: Editing Types, Next: Window-System Types, Prev: Programming Types, Up: Lisp Data Types
+
+Editing Types
+=============
+
+The types in the previous section are common to many Lisp dialects.
+XEmacs Lisp provides several additional data types for purposes
+connected with editing.
+
+* Menu:
+
+* Buffer Type:: The basic object of editing.
+* Marker Type:: A position in a buffer.
+* Extent Type:: A range in a buffer or string, maybe with properties.
+* Window Type:: Buffers are displayed in windows.
+* Frame Type:: Windows subdivide frames.
+* Device Type:: Devices group all frames on a display.
+* Console Type:: Consoles group all devices with the same keyboard.
+* Window Configuration Type:: Recording the way a frame is subdivided.
+* Event Type:: An interesting occurrence in the system.
+* Process Type:: A process running on the underlying OS.
+* Stream Type:: Receive or send characters.
+* Keymap Type:: What function a keystroke invokes.
+* Syntax Table Type:: What a character means.
+* Display Table Type:: How display tables are represented.
+* Database Type:: A connection to an external DBM or DB database.
+* Charset Type:: A character set (e.g. all Kanji characters),
+ under XEmacs/MULE.
+* Coding System Type:: An object encapsulating a way of converting between
+ different textual encodings, under XEmacs/MULE.
+* ToolTalk Message Type:: A message, in the ToolTalk IPC protocol.
+* ToolTalk Pattern Type:: A pattern, in the ToolTalk IPC protocol.
+
+\1f
+File: lispref.info, Node: Buffer Type, Next: Marker Type, Up: Editing Types
+
+Buffer Type
+-----------
+
+A "buffer" is an object that holds text that can be edited (*note
+Buffers::). Most buffers hold the contents of a disk file (*note
+Files::) so they can be edited, but some are used for other purposes.
+Most buffers are also meant to be seen by the user, and therefore
+displayed, at some time, in a window (*note Windows::). But a buffer
+need not be displayed in any window.
+
+ The contents of a buffer are much like a string, but buffers are not
+used like strings in XEmacs Lisp, and the available operations are
+different. For example, insertion of text into a buffer is very
+efficient, whereas "inserting" text into a string requires
+concatenating substrings, and the result is an entirely new string
+object.
+
+ Each buffer has a designated position called "point" (*note
+Positions::). At any time, one buffer is the "current buffer". Most
+editing commands act on the contents of the current buffer in the
+neighborhood of point. Many of the standard Emacs functions manipulate
+or test the characters in the current buffer; a whole chapter in this
+manual is devoted to describing these functions (*note Text::).
+
+ Several other data structures are associated with each buffer:
+
+ * a local syntax table (*note Syntax Tables::);
+
+ * a local keymap (*note Keymaps::);
+
+ * a local variable binding list (*note Buffer-Local Variables::);
+
+ * a list of extents (*note Extents::);
+
+ * and various other related properties.
+
+The local keymap and variable list contain entries that individually
+override global bindings or values. These are used to customize the
+behavior of programs in different buffers, without actually changing the
+programs.
+
+ A buffer may be "indirect", which means it shares the text of
+another buffer. *Note Indirect Buffers::.
+
+ Buffers have no read syntax. They print in hash notation, showing
+the buffer name.
+
+ (current-buffer)
+ => #<buffer "objects.texi">
+
+\1f
+File: lispref.info, Node: Marker Type, Next: Extent Type, Prev: Buffer Type, Up: Editing Types
+
+Marker Type
+-----------
+
+A "marker" denotes a position in a specific buffer. Markers therefore
+have two components: one for the buffer, and one for the position.
+Changes in the buffer's text automatically relocate the position value
+as necessary to ensure that the marker always points between the same
+two characters in the buffer.
+
+ Markers have no read syntax. They print in hash notation, giving the
+current character position and the name of the buffer.
+
+ (point-marker)
+ => #<marker at 50661 in objects.texi>
+
+ *Note Markers::, for information on how to test, create, copy, and
+move markers.
+
+\1f
+File: lispref.info, Node: Extent Type, Next: Window Type, Prev: Marker Type, Up: Editing Types
+
+Extent Type
+-----------
+
+An "extent" specifies temporary alteration of the display appearance of
+a part of a buffer (or string). It contains markers delimiting a range
+of the buffer, plus a property list (a list whose elements are
+alternating property names and values). Extents are used to present
+parts of the buffer temporarily in a different display style. They
+have no read syntax, and print in hash notation, giving the buffer name
+and range of positions.
+
+ Extents can exist over strings as well as buffers; the primary use
+of this is to preserve extent and text property information as text is
+copied from one buffer to another or between different parts of a
+buffer.
+
+ Extents have no read syntax. They print in hash notation, giving the
+range of text they cover, the name of the buffer or string they are in,
+the address in core, and a summary of some of the properties attached to
+the extent.
+
+ (extent-at (point))
+ => #<extent [51742, 51748) font-lock text-prop 0x90121e0 in buffer objects.texi>
+
+ *Note Extents::, for how to create and use extents.
+
+ Extents are used to implement text properties. *Note Text
+Properties::.
+
+\1f
+File: lispref.info, Node: Window Type, Next: Frame Type, Prev: Extent Type, Up: Editing Types
+
+Window Type
+-----------
+
+A "window" describes the portion of the frame that XEmacs uses to
+display a buffer. (In standard window-system usage, a "window" is what
+XEmacs calls a "frame"; XEmacs confusingly uses the term "window" to
+refer to what is called a "pane" in standard window-system usage.)
+Every window has one associated buffer, whose contents appear in the
+window. By contrast, a given buffer may appear in one window, no
+window, or several windows.
+
+ Though many windows may exist simultaneously, at any time one window
+is designated the "selected window". This is the window where the
+cursor is (usually) displayed when XEmacs is ready for a command. The
+selected window usually displays the current buffer, but this is not
+necessarily the case.
+
+ Windows are grouped on the screen into frames; each window belongs to
+one and only one frame. *Note Frame Type::.
+
+ Windows have no read syntax. They print in hash notation, giving the
+name of the buffer being displayed and a unique number assigned at the
+time the window was created. (This number can be useful because the
+buffer displayed in any given window can change frequently.)
+
+ (selected-window)
+ => #<window on "objects.texi" 0x266c>
+
+ *Note Windows::, for a description of the functions that work on
+windows.
+
+\1f
+File: lispref.info, Node: Frame Type, Next: Device Type, Prev: Window Type, Up: Editing Types
+
+Frame Type
+----------
+
+A FRAME is a rectangle on the screen (a "window" in standard
+window-system terminology) that contains one or more non-overlapping
+Emacs windows ("panes" in standard window-system terminology). A frame
+initially contains a single main window (plus perhaps a minibuffer
+window) which you can subdivide vertically or horizontally into smaller
+windows.
+
+ Frames have no read syntax. They print in hash notation, giving the
+frame's type, name as used for resourcing, and a unique number assigned
+at the time the frame was created.
+
+ (selected-frame)
+ => #<x-frame "emacs" 0x9db>
+
+ *Note Frames::, for a description of the functions that work on
+frames.
+
+\1f
+File: lispref.info, Node: Device Type, Next: Console Type, Prev: Frame Type, Up: Editing Types
+
+Device Type
+-----------
+
+A "device" represents a single display on which frames exist.
+Normally, there is only one device object, but there may be more than
+one if XEmacs is being run on a multi-headed display (e.g. an X server
+with attached color and mono screens) or if XEmacs is simultaneously
+driving frames attached to different consoles, e.g. an X display and a
+TTY connection.
+
+ Devices do not have a read syntax. They print in hash notation,
+giving the device's type, connection name, and a unique number assigned
+at the time the device was created.
+
+ (selected-device)
+ => #<x-device on ":0.0" 0x5b9>
+
+ *Note Consoles and Devices::, for a description of several functions
+related to devices.
+
+\1f
+File: lispref.info, Node: Console Type, Next: Window Configuration Type, Prev: Device Type, Up: Editing Types
+
+Console Type
+------------
+
+A "console" represents a single keyboard to which devices (i.e.
+displays on which frames exist) are connected. Normally, there is only
+one console object, but there may be more than one if XEmacs is
+simultaneously driving frames attached to different X servers and/or
+TTY connections. (XEmacs is capable of driving multiple X and TTY
+connections at the same time, and provides a robust mechanism for
+handling the differing display capabilities of such heterogeneous
+environments. A buffer with embedded glyphs and multiple fonts and
+colors, for example, will display reasonably if it simultaneously
+appears on a frame on a color X display, a frame on a mono X display,
+and a frame on a TTY connection.)
+
+ Consoles do not have a read syntax. They print in hash notation,
+giving the console's type, connection name, and a unique number assigned
+at the time the console was created.
+
+ (selected-console)
+ => #<x-console on "localhost:0" 0x5b7>
+
+ *Note Consoles and Devices::, for a description of several functions
+related to consoles.
+
+\1f
+File: lispref.info, Node: Window Configuration Type, Next: Event Type, Prev: Console Type, Up: Editing Types
+
+Window Configuration Type
+-------------------------
+
+A "window configuration" stores information about the positions, sizes,
+and contents of the windows in a frame, so you can recreate the same
+arrangement of windows later.
+
+ Window configurations do not have a read syntax. They print in hash
+notation, giving a unique number assigned at the time the window
+configuration was created.
+
+ (current-window-configuration)
+ => #<window-configuration 0x2db4>
+
+ *Note Window Configurations::, for a description of several functions
+related to window configurations.
+
+\1f
+File: lispref.info, Node: Event Type, Next: Process Type, Prev: Window Configuration Type, Up: Editing Types
+
+Event Type
+----------
+
+(not yet documented)
+
+\1f
+File: lispref.info, Node: Process Type, Next: Stream Type, Prev: Event Type, Up: Editing Types
+
+Process Type
+------------
+
+The word "process" usually means a running program. XEmacs itself runs
+in a process of this sort. However, in XEmacs Lisp, a process is a
+Lisp object that designates a subprocess created by the XEmacs process.
+Programs such as shells, GDB, ftp, and compilers, running in
+subprocesses of XEmacs, extend the capabilities of XEmacs.
+
+ An Emacs subprocess takes textual input from Emacs and returns
+textual output to Emacs for further manipulation. Emacs can also send
+signals to the subprocess.
+
+ Process objects have no read syntax. They print in hash notation,
+giving the name of the process, its associated process ID, and the
+current state of the process:
+
+ (process-list)
+ => (#<process "shell" pid 2909 state:run>)
+
+ *Note Processes::, for information about functions that create,
+delete, return information about, send input or signals to, and receive
+output from processes.
+
+\1f
+File: lispref.info, Node: Stream Type, Next: Keymap Type, Prev: Process Type, Up: Editing Types
+
+Stream Type
+-----------
+
+A "stream" is an object that can be used as a source or sink for
+characters--either to supply characters for input or to accept them as
+output. Many different types can be used this way: markers, buffers,
+strings, and functions. Most often, input streams (character sources)
+obtain characters from the keyboard, a buffer, or a file, and output
+streams (character sinks) send characters to a buffer, such as a
+`*Help*' buffer, or to the echo area.
+
+ The object `nil', in addition to its other meanings, may be used as
+a stream. It stands for the value of the variable `standard-input' or
+`standard-output'. Also, the object `t' as a stream specifies input
+using the minibuffer (*note Minibuffers::) or output in the echo area
+(*note The Echo Area::).
+
+ Streams have no special printed representation or read syntax, and
+print as whatever primitive type they are.
+
+ *Note Read and Print::, for a description of functions related to
+streams, including parsing and printing functions.
+
+\1f
+File: lispref.info, Node: Keymap Type, Next: Syntax Table Type, Prev: Stream Type, Up: Editing Types
+
+Keymap Type
+-----------
+
+A "keymap" maps keys typed by the user to commands. This mapping
+controls how the user's command input is executed.
+
+ NOTE: In XEmacs, a keymap is a separate primitive type. In FSF GNU
+Emacs, a keymap is actually a list whose CAR is the symbol `keymap'.
+
+ *Note Keymaps::, for information about creating keymaps, handling
+prefix keys, local as well as global keymaps, and changing key bindings.
+
+\1f
+File: lispref.info, Node: Syntax Table Type, Next: Display Table Type, Prev: Keymap Type, Up: Editing Types
+
+Syntax Table Type
+-----------------
+
+Under XEmacs 20, a "syntax table" is a particular type of char table.
+Under XEmacs 19, a syntax table a vector of 256 integers. In both
+cases, each element defines how one character is interpreted when it
+appears in a buffer. For example, in C mode (*note Major Modes::), the
+`+' character is punctuation, but in Lisp mode it is a valid character
+in a symbol. These modes specify different interpretations by changing
+the syntax table entry for `+'.
+
+ Syntax tables are used only for scanning text in buffers, not for
+reading Lisp expressions. The table the Lisp interpreter uses to read
+expressions is built into the XEmacs source code and cannot be changed;
+thus, to change the list delimiters to be `{' and `}' instead of `('
+and `)' would be impossible.
+
+ *Note Syntax Tables::, for details about syntax classes and how to
+make and modify syntax tables.
+
+\1f
+File: lispref.info, Node: Display Table Type, Next: Database Type, Prev: Syntax Table Type, Up: Editing Types
+
+Display Table Type
+------------------
+
+A "display table" specifies how to display each character code. Each
+buffer and each window can have its own display table. A display table
+is actually a vector of length 256, although in XEmacs 20 this may
+change to be a particular type of char table. *Note Display Tables::.
+
+\1f
+File: lispref.info, Node: Database Type, Next: Charset Type, Prev: Display Table Type, Up: Editing Types
+
+Database Type
+-------------
+
+(not yet documented)
+
+\1f
+File: lispref.info, Node: Charset Type, Next: Coding System Type, Prev: Database Type, Up: Editing Types
+
+Charset Type
+------------
+
+(not yet documented)
+
+\1f
+File: lispref.info, Node: Coding System Type, Next: ToolTalk Message Type, Prev: Charset Type, Up: Editing Types
+
+Coding System Type
+------------------
+
+(not yet documented)
+
+\1f
+File: lispref.info, Node: ToolTalk Message Type, Next: ToolTalk Pattern Type, Prev: Coding System Type, Up: Editing Types
+
+ToolTalk Message Type
+---------------------
+
+(not yet documented)
+
+\1f
+File: lispref.info, Node: ToolTalk Pattern Type, Prev: ToolTalk Message Type, Up: Editing Types
+
+ToolTalk Pattern Type
+---------------------
+
+(not yet documented)
+
+\1f
+File: lispref.info, Node: Window-System Types, Next: Type Predicates, Prev: Editing Types, Up: Lisp Data Types
+
+Window-System Types
+===================
+
+XEmacs also has some types that represent objects such as faces
+(collections of display characters), fonts, and pixmaps that are
+commonly found in windowing systems.
+
+* Menu:
+
+* Face Type:: A collection of display characteristics.
+* Glyph Type:: An image appearing in a buffer or elsewhere.
+* Specifier Type:: A way of controlling display characteristics on
+ a per-buffer, -frame, -window, or -device level.
+* Font Instance Type:: The way a font appears on a particular device.
+* Color Instance Type:: The way a color appears on a particular device.
+* Image Instance Type:: The way an image appears on a particular device.
+* Toolbar Button Type:: An object representing a button in a toolbar.
+* Subwindow Type:: An externally-controlled window-system window
+ appearing in a buffer.
+* X Resource Type:: A miscellaneous X resource, if Epoch support was
+ compiled into XEmacs.
+
+\1f
+File: lispref.info, Node: Face Type, Next: Glyph Type, Up: Window-System Types
+
+Face Type
+---------
+
+(not yet documented)
+
+\1f
+File: lispref.info, Node: Glyph Type, Next: Specifier Type, Prev: Face Type, Up: Window-System Types
+
+Glyph Type
+----------
+
+(not yet documented)
+
+\1f
+File: lispref.info, Node: Specifier Type, Next: Font Instance Type, Prev: Glyph Type, Up: Window-System Types
+
+Specifier Type
+--------------
+
+(not yet documented)
+
+\1f
+File: lispref.info, Node: Font Instance Type, Next: Color Instance Type, Prev: Specifier Type, Up: Window-System Types
+
+Font Instance Type
+------------------
+
+(not yet documented)
+
+\1f
+File: lispref.info, Node: Color Instance Type, Next: Image Instance Type, Prev: Font Instance Type, Up: Window-System Types
+
+Color Instance Type
+-------------------
+
+(not yet documented)
+
+\1f
+File: lispref.info, Node: Image Instance Type, Next: Toolbar Button Type, Prev: Color Instance Type, Up: Window-System Types
+
+Image Instance Type
+-------------------
+
+(not yet documented)
+
+\1f
+File: lispref.info, Node: Toolbar Button Type, Next: Subwindow Type, Prev: Image Instance Type, Up: Window-System Types
+
+Toolbar Button Type
+-------------------
+
+(not yet documented)
+
+\1f
+File: lispref.info, Node: Subwindow Type, Next: X Resource Type, Prev: Toolbar Button Type, Up: Window-System Types
+
+Subwindow Type
+--------------
+
+(not yet documented)
+
+\1f
+File: lispref.info, Node: X Resource Type, Prev: Subwindow Type, Up: Window-System Types
+
+X Resource Type
+---------------
+
+(not yet documented)
+
+\1f
+File: lispref.info, Node: Type Predicates, Next: Equality Predicates, Prev: Window-System Types, Up: Lisp Data Types
+
+Type Predicates
+===============
+
+The XEmacs Lisp interpreter itself does not perform type checking on
+the actual arguments passed to functions when they are called. It could
+not do so, since function arguments in Lisp do not have declared data
+types, as they do in other programming languages. It is therefore up to
+the individual function to test whether each actual argument belongs to
+a type that the function can use.
+
+ All built-in functions do check the types of their actual arguments
+when appropriate, and signal a `wrong-type-argument' error if an
+argument is of the wrong type. For example, here is what happens if you
+pass an argument to `+' that it cannot handle:
+
+ (+ 2 'a)
+ error--> Wrong type argument: integer-or-marker-p, a
+
+ If you want your program to handle different types differently, you
+must do explicit type checking. The most common way to check the type
+of an object is to call a "type predicate" function. Emacs has a type
+predicate for each type, as well as some predicates for combinations of
+types.
+
+ A type predicate function takes one argument; it returns `t' if the
+argument belongs to the appropriate type, and `nil' otherwise.
+Following a general Lisp convention for predicate functions, most type
+predicates' names end with `p'.
+
+ Here is an example which uses the predicates `listp' to check for a
+list and `symbolp' to check for a symbol.
+
+ (defun add-on (x)
+ (cond ((symbolp x)
+ ;; If X is a symbol, put it on LIST.
+ (setq list (cons x list)))
+ ((listp x)
+ ;; If X is a list, add its elements to LIST.
+ (setq list (append x list)))
+ (t
+ ;; We only handle symbols and lists.
+ (error "Invalid argument %s in add-on" x))))
+
+ Here is a table of predefined type predicates, in alphabetical order,
+with references to further information.
+
+`annotationp'
+ *Note annotationp: Annotation Primitives.
+
+`arrayp'
+ *Note arrayp: Array Functions.
+
+`atom'
+ *Note atom: List-related Predicates.
+
+`bit-vector-p'
+ *Note bit-vector-p: Bit Vector Functions.
+
+`bitp'
+ *Note bitp: Bit Vector Functions.
+
+`boolean-specifier-p'
+ *Note boolean-specifier-p: Specifier Types.
+
+`buffer-glyph-p'
+ *Note buffer-glyph-p: Glyph Types.
+
+`buffer-live-p'
+ *Note buffer-live-p: Killing Buffers.
+
+`bufferp'
+ *Note bufferp: Buffer Basics.
+
+`button-event-p'
+ *Note button-event-p: Event Predicates.
+
+`button-press-event-p'
+ *Note button-press-event-p: Event Predicates.
+
+`button-release-event-p'
+ *Note button-release-event-p: Event Predicates.
+
+`case-table-p'
+ *Note case-table-p: Case Tables.
+
+`char-int-p'
+ *Note char-int-p: Character Codes.
+
+`char-or-char-int-p'
+ *Note char-or-char-int-p: Character Codes.
+
+`char-or-string-p'
+ *Note char-or-string-p: Predicates for Strings.
+
+`char-table-p'
+ *Note char-table-p: Char Tables.
+
+`characterp'
+ *Note characterp: Predicates for Characters.
+
+`color-instance-p'
+ *Note color-instance-p: Colors.
+
+`color-pixmap-image-instance-p'
+ *Note color-pixmap-image-instance-p: Image Instance Types.
+
+`color-specifier-p'
+ *Note color-specifier-p: Specifier Types.
+
+`commandp'
+ *Note commandp: Interactive Call.
+
+`compiled-function-p'
+ *Note compiled-function-p: Compiled-Function Type.
+
+`console-live-p'
+ *Note console-live-p: Connecting to a Console or Device.
+
+`consolep'
+ *Note consolep: Consoles and Devices.
+
+`consp'
+ *Note consp: List-related Predicates.
+
+`database-live-p'
+ *Note database-live-p: Connecting to a Database.
+
+`databasep'
+ *Note databasep: Databases.
+
+`device-live-p'
+ *Note device-live-p: Connecting to a Console or Device.
+
+`device-or-frame-p'
+ *Note device-or-frame-p: Basic Device Functions.
+
+`devicep'
+ *Note devicep: Consoles and Devices.
+
+`eval-event-p'
+ *Note eval-event-p: Event Predicates.
+
+`event-live-p'
+ *Note event-live-p: Event Predicates.
+
+`eventp'
+ *Note eventp: Events.
+
+`extent-live-p'
+ *Note extent-live-p: Creating and Modifying Extents.
+
+`extentp'
+ *Note extentp: Extents.
+
+`face-boolean-specifier-p'
+ *Note face-boolean-specifier-p: Specifier Types.
+
+`facep'
+ *Note facep: Basic Face Functions.
+
+`floatp'
+ *Note floatp: Predicates on Numbers.
+
+`font-instance-p'
+ *Note font-instance-p: Fonts.
+
+`font-specifier-p'
+ *Note font-specifier-p: Specifier Types.
+
+`frame-live-p'
+ *Note frame-live-p: Deleting Frames.
+
+`framep'
+ *Note framep: Frames.
+
+`functionp'
+ (not yet documented)
+
+`generic-specifier-p'
+ *Note generic-specifier-p: Specifier Types.
+
+`glyphp'
+ *Note glyphp: Glyphs.
+
+`hash-table-p'
+ *Note hash-table-p: Hash Tables.
+
+`icon-glyph-p'
+ *Note icon-glyph-p: Glyph Types.
+
+`image-instance-p'
+ *Note image-instance-p: Images.
+
+`image-specifier-p'
+ *Note image-specifier-p: Specifier Types.
+
+`integer-char-or-marker-p'
+ *Note integer-char-or-marker-p: Predicates on Markers.
+
+`integer-or-char-p'
+ *Note integer-or-char-p: Predicates for Characters.
+
+`integer-or-marker-p'
+ *Note integer-or-marker-p: Predicates on Markers.
+
+`integer-specifier-p'
+ *Note integer-specifier-p: Specifier Types.
+
+`integerp'
+ *Note integerp: Predicates on Numbers.
+
+`itimerp'
+ (not yet documented)
+
+`key-press-event-p'
+ *Note key-press-event-p: Event Predicates.
+
+`keymapp'
+ *Note keymapp: Creating Keymaps.
+
+`keywordp'
+ (not yet documented)
+
+`listp'
+ *Note listp: List-related Predicates.
+
+`markerp'
+ *Note markerp: Predicates on Markers.
+
+`misc-user-event-p'
+ *Note misc-user-event-p: Event Predicates.
+
+`mono-pixmap-image-instance-p'
+ *Note mono-pixmap-image-instance-p: Image Instance Types.
+
+`motion-event-p'
+ *Note motion-event-p: Event Predicates.
+
+`mouse-event-p'
+ *Note mouse-event-p: Event Predicates.
+
+`natnum-specifier-p'
+ *Note natnum-specifier-p: Specifier Types.
+
+`natnump'
+ *Note natnump: Predicates on Numbers.
+
+`nlistp'
+ *Note nlistp: List-related Predicates.
+
+`nothing-image-instance-p'
+ *Note nothing-image-instance-p: Image Instance Types.
+
+`number-char-or-marker-p'
+ *Note number-char-or-marker-p: Predicates on Markers.
+
+`number-or-marker-p'
+ *Note number-or-marker-p: Predicates on Markers.
+
+`numberp'
+ *Note numberp: Predicates on Numbers.
+
+`pointer-glyph-p'
+ *Note pointer-glyph-p: Glyph Types.
+
+`pointer-image-instance-p'
+ *Note pointer-image-instance-p: Image Instance Types.
+
+`process-event-p'
+ *Note process-event-p: Event Predicates.
+
+`processp'
+ *Note processp: Processes.
+
+`range-table-p'
+ *Note range-table-p: Range Tables.
+
+`ringp'
+ (not yet documented)
+
+`sequencep'
+ *Note sequencep: Sequence Functions.
+
+`specifierp'
+ *Note specifierp: Specifiers.
+
+`stringp'
+ *Note stringp: Predicates for Strings.
+
+`subrp'
+ *Note subrp: Function Cells.
+
+`subwindow-image-instance-p'
+ *Note subwindow-image-instance-p: Image Instance Types.
+
+`subwindowp'
+ *Note subwindowp: Subwindows.
+
+`symbolp'
+ *Note symbolp: Symbols.
+
+`syntax-table-p'
+ *Note syntax-table-p: Syntax Tables.
+
+`text-image-instance-p'
+ *Note text-image-instance-p: Image Instance Types.
+
+`timeout-event-p'
+ *Note timeout-event-p: Event Predicates.
+
+`toolbar-button-p'
+ *Note toolbar-button-p: Toolbar.
+
+`toolbar-specifier-p'
+ *Note toolbar-specifier-p: Toolbar.
+
+`user-variable-p'
+ *Note user-variable-p: Defining Variables.
+
+`vectorp'
+ *Note vectorp: Vectors.
+
+`weak-list-p'
+ *Note weak-list-p: Weak Lists.
+
+`window-configuration-p'
+ *Note window-configuration-p: Window Configurations.
+
+`window-live-p'
+ *Note window-live-p: Deleting Windows.
+
+`windowp'
+ *Note windowp: Basic Windows.
+
+ The most general way to check the type of an object is to call the
+function `type-of'. Recall that each object belongs to one and only
+one primitive type; `type-of' tells you which one (*note Lisp Data
+Types::). But `type-of' knows nothing about non-primitive types. In
+most cases, it is more convenient to use type predicates than `type-of'.
+
+ - Function: type-of object
+ This function returns a symbol naming the primitive type of
+ OBJECT. The value is one of `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', or `x-resource'.
+
+ (type-of 1)
+ => integer
+ (type-of 'nil)
+ => symbol
+ (type-of '()) ; `()' is `nil'.
+ => symbol
+ (type-of '(x))
+ => cons
+
+\1f
+File: lispref.info, Node: Equality Predicates, Prev: Type Predicates, Up: Lisp Data Types
+
+Equality Predicates
+===================
+
+Here we describe two functions that test for equality between any two
+objects. Other functions test equality between objects of specific
+types, e.g., strings. For these predicates, see the appropriate chapter
+describing the data type.
+
+ - Function: eq object1 object2
+ This function returns `t' if OBJECT1 and OBJECT2 are the same
+ object, `nil' otherwise. The "same object" means that a change in
+ one will be reflected by the same change in the other.
+
+ `eq' returns `t' if OBJECT1 and OBJECT2 are integers with the same
+ value. Also, since symbol names are normally unique, if the
+ arguments are symbols with the same name, they are `eq'. For
+ other types (e.g., lists, vectors, strings), two arguments with
+ the same contents or elements are not necessarily `eq' to each
+ other: they are `eq' only if they are the same object.
+
+ (The `make-symbol' function returns an uninterned symbol that is
+ not interned in the standard `obarray'. When uninterned symbols
+ are in use, symbol names are no longer unique. Distinct symbols
+ with the same name are not `eq'. *Note Creating Symbols::.)
+
+ NOTE: Under XEmacs 19, characters are really just integers, and
+ thus characters and integers are `eq'. Under XEmacs 20, it was
+ necessary to preserve remnants of this in function such as `old-eq'
+ in order to maintain byte-code compatibility. Byte code compiled
+ under any Emacs 19 will automatically have calls to `eq' mapped to
+ `old-eq' when executed under XEmacs 20.
+
+ (eq 'foo 'foo)
+ => t
+
+ (eq 456 456)
+ => t
+
+ (eq "asdf" "asdf")
+ => nil
+
+ (eq '(1 (2 (3))) '(1 (2 (3))))
+ => nil
+
+ (setq foo '(1 (2 (3))))
+ => (1 (2 (3)))
+ (eq foo foo)
+ => t
+ (eq foo '(1 (2 (3))))
+ => nil
+
+ (eq [(1 2) 3] [(1 2) 3])
+ => nil
+
+ (eq (point-marker) (point-marker))
+ => nil
+
+
+ - Function: old-eq object1 object2
+ This function exists under XEmacs 20 and is exactly like `eq'
+ except that it suffers from the char-int confoundance disease. In
+ other words, it returns `t' if given a character and the
+ equivalent integer, even though the objects are of different types!
+ You should _not_ ever call this function explicitly in your code.
+ However, be aware that all calls to `eq' in byte code compiled
+ under version 19 map to `old-eq' in XEmacs 20. (Likewise for
+ `old-equal', `old-memq', `old-member', `old-assq' and
+ `old-assoc'.)
+
+ ;; Remember, this does not apply under XEmacs 19.
+ ?A
+ => ?A
+ (char-int ?A)
+ => 65
+ (old-eq ?A 65)
+ => t ; Eek, we've been infected.
+ (eq ?A 65)
+ => nil ; We are still healthy.
+
+ - Function: equal object1 object2
+ This function returns `t' if OBJECT1 and OBJECT2 have equal
+ components, `nil' otherwise. Whereas `eq' tests if its arguments
+ are the same object, `equal' looks inside nonidentical arguments
+ to see if their elements are the same. So, if two objects are
+ `eq', they are `equal', but the converse is not always true.
+
+ (equal 'foo 'foo)
+ => t
+
+ (equal 456 456)
+ => t
+
+ (equal "asdf" "asdf")
+ => t
+ (eq "asdf" "asdf")
+ => nil
+
+ (equal '(1 (2 (3))) '(1 (2 (3))))
+ => t
+ (eq '(1 (2 (3))) '(1 (2 (3))))
+ => nil
+
+ (equal [(1 2) 3] [(1 2) 3])
+ => t
+ (eq [(1 2) 3] [(1 2) 3])
+ => nil
+
+ (equal (point-marker) (point-marker))
+ => t
+
+ (eq (point-marker) (point-marker))
+ => nil
+
+ Comparison of strings is case-sensitive.
+
+ Note that in FSF GNU Emacs, comparison of strings takes into
+ account their text properties, and you have to use `string-equal'
+ if you want only the strings themselves compared. This difference
+ does not exist in XEmacs; `equal' and `string-equal' always return
+ the same value on the same strings.
+
+ (equal "asdf" "ASDF")
+ => nil
+
+ Two distinct buffers are never `equal', even if their contents are
+ the same.
+
+ The test for equality is implemented recursively, and circular lists
+may therefore cause infinite recursion (leading to an error).
+
+\1f
+File: lispref.info, Node: Numbers, Next: Strings and Characters, Prev: Lisp Data Types, Up: Top
+
+Numbers
+*******
+
+XEmacs supports two numeric data types: "integers" and "floating point
+numbers". Integers are whole numbers such as -3, 0, #b0111, #xFEED,
+#o744. Their values are exact. The number prefixes `#b', `#o', and
+`#x' are supported to represent numbers in binary, octal, and
+hexadecimal notation (or radix). Floating point numbers are numbers
+with fractional parts, such as -4.5, 0.0, or 2.71828. They can also be
+expressed in exponential notation: 1.5e2 equals 150; in this example,
+`e2' stands for ten to the second power, and is multiplied by 1.5.
+Floating point values are not exact; they have a fixed, limited amount
+of precision.
+
+* Menu:
+
+* Integer Basics:: Representation and range of integers.
+* Float Basics:: Representation and range of floating point.
+* Predicates on Numbers:: Testing for numbers.
+* Comparison of Numbers:: Equality and inequality predicates.
+* Numeric Conversions:: Converting float to integer and vice versa.
+* Arithmetic Operations:: How to add, subtract, multiply and divide.
+* Rounding Operations:: Explicitly rounding floating point numbers.
+* Bitwise Operations:: Logical and, or, not, shifting.
+* Math Functions:: Trig, exponential and logarithmic functions.
+* Random Numbers:: Obtaining random integers, predictable or not.
+
+\1f
+File: lispref.info, Node: Integer Basics, Next: Float Basics, Up: Numbers
+
+Integer Basics
+==============
+
+The range of values for an integer depends on the machine. The minimum
+range is -134217728 to 134217727 (28 bits; i.e., -2**27 to 2**27 - 1),
+but some machines may provide a wider range. Many examples in this
+chapter assume an integer has 28 bits.
+
+ The Lisp reader reads an integer as a sequence of digits with
+optional initial sign and optional final period.
+
+ 1 ; The integer 1.
+ 1. ; The integer 1.
+ +1 ; Also the integer 1.
+ -1 ; The integer -1.
+ 268435457 ; Also the integer 1, due to overflow.
+ 0 ; The integer 0.
+ -0 ; The integer 0.
+
+ To understand how various functions work on integers, especially the
+bitwise operators (*note Bitwise Operations::), it is often helpful to
+view the numbers in their binary form.
+
+ In 28-bit binary, the decimal integer 5 looks like this:
+
+ 0000 0000 0000 0000 0000 0000 0101
+
+(We have inserted spaces between groups of 4 bits, and two spaces
+between groups of 8 bits, to make the binary integer easier to read.)
+
+ The integer -1 looks like this:
+
+ 1111 1111 1111 1111 1111 1111 1111
+
+-1 is represented as 28 ones. (This is called "two's complement"
+notation.)
+
+ The negative integer, -5, is creating by subtracting 4 from -1. In
+binary, the decimal integer 4 is 100. Consequently, -5 looks like this:
+
+ 1111 1111 1111 1111 1111 1111 1011
+
+ In this implementation, the largest 28-bit binary integer is the
+decimal integer 134,217,727. In binary, it looks like this:
+
+ 0111 1111 1111 1111 1111 1111 1111
+
+ Since the arithmetic functions do not check whether integers go
+outside their range, when you add 1 to 134,217,727, the value is the
+negative integer -134,217,728:
+
+ (+ 1 134217727)
+ => -134217728
+ => 1000 0000 0000 0000 0000 0000 0000
+
+ Many of the following functions accept markers for arguments as well
+as integers. (*Note Markers::.) More precisely, the actual arguments
+to such functions may be either integers or markers, which is why we
+often give these arguments the name INT-OR-MARKER. When the argument
+value is a marker, its position value is used and its buffer is ignored.
+
+\1f
+File: lispref.info, Node: Float Basics, Next: Predicates on Numbers, Prev: Integer Basics, Up: Numbers
+
+Floating Point Basics
+=====================
+
+XEmacs supports floating point numbers. The precise range of floating
+point numbers is machine-specific; it is the same as the range of the C
+data type `double' on the machine in question.
+
+ 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. You can also use a minus sign to write
+negative floating point numbers, as in `-1.0'.
+
+ Most modern computers support the IEEE floating point standard, which
+provides for positive infinity and negative infinity as floating point
+values. It also provides for a class of values called NaN or
+"not-a-number"; numerical functions return such values in cases where
+there is no correct answer. For example, `(sqrt -1.0)' returns a NaN.
+For practical purposes, there's no significant difference between
+different NaN values in XEmacs Lisp, and there's no rule for precisely
+which NaN value should be used in a particular case, so this manual
+doesn't try to distinguish them. XEmacs Lisp has no read syntax for
+NaNs or infinities; perhaps we should create a syntax in the future.
+
+ You can use `logb' to extract the binary exponent of a floating
+point number (or estimate the logarithm of an integer):
+
+ - Function: logb number
+ This function returns the binary exponent of NUMBER. More
+ precisely, the value is the logarithm of NUMBER base 2, rounded
+ down to an integer.
+
+\1f
+File: lispref.info, Node: Predicates on Numbers, Next: Comparison of Numbers, Prev: Float Basics, Up: Numbers
+
+Type Predicates for Numbers
+===========================
+
+The functions in this section test whether the argument is a number or
+whether it is a certain sort of number. The functions `integerp' and
+`floatp' can take any type of Lisp object as argument (the predicates
+would not be of much use otherwise); but the `zerop' predicate requires
+a number as its argument. See also `integer-or-marker-p',
+`integer-char-or-marker-p', `number-or-marker-p' and
+`number-char-or-marker-p', in *Note Predicates on Markers::.
+
+ - Function: floatp object
+ This predicate tests whether its argument is a floating point
+ number and returns `t' if so, `nil' otherwise.
+
+ `floatp' does not exist in Emacs versions 18 and earlier.
+
+ - Function: integerp object
+ This predicate tests whether its argument is an integer, and
+ returns `t' if so, `nil' otherwise.
+
+ - Function: numberp object
+ This predicate tests whether its argument is a number (either
+ integer or floating point), and returns `t' if so, `nil' otherwise.
+
+ - Function: natnump object
+ The `natnump' predicate (whose name comes from the phrase
+ "natural-number-p") tests to see whether its argument is a
+ nonnegative integer, and returns `t' if so, `nil' otherwise. 0 is
+ considered non-negative.
+
+ - Function: zerop number
+ This predicate tests whether its argument is zero, and returns `t'
+ if so, `nil' otherwise. The argument must be a number.
+
+ These two forms are equivalent: `(zerop x)' == `(= x 0)'.
+
+\1f
+File: lispref.info, Node: Comparison of Numbers, Next: Numeric Conversions, Prev: Predicates on Numbers, Up: Numbers
+
+Comparison of Numbers
+=====================
+
+To test numbers for numerical equality, you should normally use `=',
+not `eq'. There can be many distinct floating point number objects
+with the same numeric value. If you use `eq' to compare them, then you
+test whether two values are the same _object_. By contrast, `='
+compares only the numeric values of the objects.
+
+ At present, each integer value has a unique Lisp object in XEmacs
+Lisp. Therefore, `eq' is equivalent to `=' where integers are
+concerned. It is sometimes convenient to use `eq' for comparing an
+unknown value with an integer, because `eq' does not report an error if
+the unknown value is not a number--it accepts arguments of any type.
+By contrast, `=' signals an error if the arguments are not numbers or
+markers. However, it is a good idea to use `=' if you can, even for
+comparing integers, just in case we change the representation of
+integers in a future XEmacs version.
+
+ There is another wrinkle: because floating point arithmetic is not
+exact, it is often a bad idea to check for equality of two floating
+point values. Usually it is better to test for approximate equality.
+Here's a function to do this:
+
+ (defconst fuzz-factor 1.0e-6)
+ (defun approx-equal (x y)
+ (or (and (= x 0) (= y 0))
+ (< (/ (abs (- x y))
+ (max (abs x) (abs y)))
+ fuzz-factor)))
+
+ Common Lisp note: Comparing numbers in Common Lisp always requires
+ `=' because Common Lisp implements multi-word integers, and two
+ distinct integer objects can have the same numeric value. XEmacs
+ Lisp can have just one integer object for any given value because
+ it has a limited range of integer values.
+
+ In addition to numbers, all of the following functions also accept
+characters and markers as arguments, and treat them as their number
+equivalents.
+
+ - Function: = number &rest more-numbers
+ This function returns `t' if all of its arguments are numerically
+ equal, `nil' otherwise.
+
+ (= 5)
+ => t
+ (= 5 6)
+ => nil
+ (= 5 5.0)
+ => t
+ (= 5 5 6)
+ => nil
+
+ - Function: /= number &rest more-numbers
+ This function returns `t' if no two arguments are numerically
+ equal, `nil' otherwise.
+
+ (/= 5 6)
+ => t
+ (/= 5 5 6)
+ => nil
+ (/= 5 6 1)
+ => t
+
+ - Function: < number &rest more-numbers
+ This function returns `t' if the sequence of its arguments is
+ monotonically increasing, `nil' otherwise.
+
+ (< 5 6)
+ => t
+ (< 5 6 6)
+ => nil
+ (< 5 6 7)
+ => t
+
+ - Function: <= number &rest more-numbers
+ This function returns `t' if the sequence of its arguments is
+ monotonically nondecreasing, `nil' otherwise.
+
+ (<= 5 6)
+ => t
+ (<= 5 6 6)
+ => t
+ (<= 5 6 5)
+ => nil
+
+ - Function: > number &rest more-numbers
+ This function returns `t' if the sequence of its arguments is
+ monotonically decreasing, `nil' otherwise.
+
+ - Function: >= number &rest more-numbers
+ This function returns `t' if the sequence of its arguments is
+ monotonically nonincreasing, `nil' otherwise.
+
+ - Function: max number &rest more-numbers
+ This function returns the largest of its arguments.
+
+ (max 20)
+ => 20
+ (max 1 2.5)
+ => 2.5
+ (max 1 3 2.5)
+ => 3
+
+ - Function: min number &rest more-numbers
+ This function returns the smallest of its arguments.
+
+ (min -4 1)
+ => -4
+
+\1f
+File: lispref.info, Node: Numeric Conversions, Next: Arithmetic Operations, Prev: Comparison of Numbers, Up: Numbers
+
+Numeric Conversions
+===================
+
+To convert an integer to floating point, use the function `float'.
+
+ - Function: float number
+ This returns NUMBER converted to floating point. If NUMBER is
+ already a floating point number, `float' returns it unchanged.
+
+ There are four functions to convert floating point numbers to
+integers; they differ in how they round. These functions accept
+integer arguments also, and return such arguments unchanged.
+
+ - Function: truncate number
+ This returns NUMBER, converted to an integer by rounding towards
+ zero.
+
+ - Function: floor number &optional divisor
+ This returns NUMBER, converted to an integer by rounding downward
+ (towards negative infinity).
+
+ If DIVISOR is specified, NUMBER is divided by DIVISOR before the
+ floor is taken; this is the division operation that corresponds to
+ `mod'. An `arith-error' results if DIVISOR is 0.
+
+ - Function: ceiling number
+ This returns NUMBER, converted to an integer by rounding upward
+ (towards positive infinity).
+
+ - Function: round number
+ This returns NUMBER, converted to an integer by rounding towards
+ the nearest integer. Rounding a value equidistant between two
+ integers may choose the integer closer to zero, or it may prefer
+ an even integer, depending on your machine.
+
+\1f
+File: lispref.info, Node: Arithmetic Operations, Next: Rounding Operations, Prev: Numeric Conversions, Up: Numbers
+
+Arithmetic Operations
+=====================
+
+XEmacs Lisp provides the traditional four arithmetic operations:
+addition, subtraction, multiplication, and division. Remainder and
+modulus functions supplement the division functions. The functions to
+add or subtract 1 are provided because they are traditional in Lisp and
+commonly used.
+
+ All of these functions except `%' return a floating point value if
+any argument is floating.
+
+ It is important to note that in XEmacs Lisp, arithmetic functions do
+not check for overflow. Thus `(1+ 134217727)' may evaluate to
+-134217728, depending on your hardware.
+
+ - Function: 1+ number
+ This function returns NUMBER plus one. NUMBER may be a number,
+ character or marker. Markers and characters are converted to
+ integers.
+
+ For example,
+
+ (setq foo 4)
+ => 4
+ (1+ foo)
+ => 5
+
+ This function is not analogous to the C operator `++'--it does not
+ increment a variable. It just computes a sum. Thus, if we
+ continue,
+
+ foo
+ => 4
+
+ If you want to increment the variable, you must use `setq', like
+ this:
+
+ (setq foo (1+ foo))
+ => 5
+
+ Now that the `cl' package is always available from lisp code, a
+ more convenient and natural way to increment a variable is
+ `(incf foo)'.
+
+ - Function: 1- number
+ This function returns NUMBER minus one. NUMBER may be a number,
+ character or marker. Markers and characters are converted to
+ integers.
+
+ - Function: abs number
+ This returns the absolute value of NUMBER.
+
+ - Function: + &rest numbers
+ This function adds its arguments together. When given no
+ arguments, `+' returns 0.
+
+ If any of the arguments are characters or markers, they are first
+ converted to integers.
+
+ (+)
+ => 0
+ (+ 1)
+ => 1
+ (+ 1 2 3 4)
+ => 10
+
+ - Function: - &optional number &rest other-numbers
+ The `-' function serves two purposes: negation and subtraction.
+ When `-' has a single argument, the value is the negative of the
+ argument. When there are multiple arguments, `-' subtracts each of
+ the OTHER-NUMBERS from NUMBER, cumulatively. If there are no
+ arguments, an error is signaled.
+
+ If any of the arguments are characters or markers, they are first
+ converted to integers.
+
+ (- 10 1 2 3 4)
+ => 0
+ (- 10)
+ => -10
+ (-)
+ => 0
+
+ - Function: * &rest numbers
+ This function multiplies its arguments together, and returns the
+ product. When given no arguments, `*' returns 1.
+
+ If any of the arguments are characters or markers, they are first
+ converted to integers.
+
+ (*)
+ => 1
+ (* 1)
+ => 1
+ (* 1 2 3 4)
+ => 24
+
+ - Function: / dividend &rest divisors
+ The `/' function serves two purposes: inversion and division. When
+ `/' has a single argument, the value is the inverse of the
+ argument. When there are multiple arguments, `/' divides DIVIDEND
+ by each of the DIVISORS, cumulatively, returning the quotient. If
+ there are no arguments, an error is signaled.
+
+ If none of the arguments are floats, then the result is an integer.
+ This means the result has to be rounded. On most machines, the
+ result is rounded towards zero after each division, but some
+ machines may round differently with negative arguments. This is
+ because the Lisp function `/' is implemented using the C division
+ operator, which also permits machine-dependent rounding. As a
+ practical matter, all known machines round in the standard fashion.
+
+ If any of the arguments are characters or markers, they are first
+ converted to integers.
+
+ If you divide by 0, an `arith-error' error is signaled. (*Note
+ Errors::.)
+
+ (/ 6 2)
+ => 3
+ (/ 5 2)
+ => 2
+ (/ 25 3 2)
+ => 4
+ (/ 3.0)
+ => 0.3333333333333333
+ (/ -17 6)
+ => -2
+
+ The result of `(/ -17 6)' could in principle be -3 on some
+ machines.
+
+ - Function: % dividend divisor
+ This function returns the integer remainder after division of
+ DIVIDEND by DIVISOR. The arguments must be integers or markers.
+
+ For negative arguments, the remainder is in principle
+ machine-dependent since the quotient is; but in practice, all
+ known machines behave alike.
+
+ An `arith-error' results if DIVISOR is 0.
+
+ (% 9 4)
+ => 1
+ (% -9 4)
+ => -1
+ (% 9 -4)
+ => 1
+ (% -9 -4)
+ => -1
+
+ For any two integers DIVIDEND and DIVISOR,
+
+ (+ (% DIVIDEND DIVISOR)
+ (* (/ DIVIDEND DIVISOR) DIVISOR))
+
+ always equals DIVIDEND.
+
+ - Function: mod dividend divisor
+ This function returns the value of DIVIDEND modulo DIVISOR; in
+ other words, the remainder after division of DIVIDEND by DIVISOR,
+ but with the same sign as DIVISOR. The arguments must be numbers
+ or markers.
+
+ Unlike `%', `mod' returns a well-defined result for negative
+ arguments. It also permits floating point arguments; it rounds the
+ quotient downward (towards minus infinity) to an integer, and uses
+ that quotient to compute the remainder.
+
+ An `arith-error' results if DIVISOR is 0.
+
+ (mod 9 4)
+ => 1
+ (mod -9 4)
+ => 3
+ (mod 9 -4)
+ => -3
+ (mod -9 -4)
+ => -1
+ (mod 5.5 2.5)
+ => .5
+
+ For any two numbers DIVIDEND and DIVISOR,
+
+ (+ (mod DIVIDEND DIVISOR)
+ (* (floor DIVIDEND DIVISOR) DIVISOR))
+
+ always equals DIVIDEND, subject to rounding error if either
+ argument is floating point. For `floor', see *Note Numeric
+ Conversions::.
+
+\1f
+File: lispref.info, Node: Rounding Operations, Next: Bitwise Operations, Prev: Arithmetic Operations, Up: Numbers
+
+Rounding Operations
+===================
+
+The functions `ffloor', `fceiling', `fround' and `ftruncate' take a
+floating point argument and return a floating point result whose value
+is a nearby integer. `ffloor' returns the nearest integer below;
+`fceiling', the nearest integer above; `ftruncate', the nearest integer
+in the direction towards zero; `fround', the nearest integer.
+
+ - Function: ffloor number
+ This function rounds NUMBER to the next lower integral value, and
+ returns that value as a floating point number.
+
+ - Function: fceiling number
+ This function rounds NUMBER to the next higher integral value, and
+ returns that value as a floating point number.
+
+ - Function: ftruncate number
+ This function rounds NUMBER towards zero to an integral value, and
+ returns that value as a floating point number.
+
+ - Function: fround number
+ This function rounds NUMBER to the nearest integral value, and
+ returns that value as a floating point number.
+
+\1f
+File: lispref.info, Node: Bitwise Operations, Next: Math Functions, Prev: Rounding Operations, Up: Numbers
+
+Bitwise Operations on Integers
+==============================
+
+In a computer, an integer is represented as a binary number, a sequence
+of "bits" (digits which are either zero or one). A bitwise operation
+acts on the individual bits of such a sequence. For example,
+"shifting" moves the whole sequence left or right one or more places,
+reproducing the same pattern "moved over".
+
+ The bitwise operations in XEmacs Lisp apply only to integers.
+
+ - Function: lsh integer1 count
+ `lsh', which is an abbreviation for "logical shift", shifts the
+ bits in INTEGER1 to the left COUNT places, or to the right if
+ COUNT is negative, bringing zeros into the vacated bits. If COUNT
+ is negative, `lsh' shifts zeros into the leftmost
+ (most-significant) bit, producing a positive result even if
+ INTEGER1 is negative. Contrast this with `ash', below.
+
+ Here are two examples of `lsh', shifting a pattern of bits one
+ place to the left. We show only the low-order eight bits of the
+ binary pattern; the rest are all zero.
+
+ (lsh 5 1)
+ => 10
+ ;; Decimal 5 becomes decimal 10.
+ 00000101 => 00001010
+
+ (lsh 7 1)
+ => 14
+ ;; Decimal 7 becomes decimal 14.
+ 00000111 => 00001110
+
+ As the examples illustrate, shifting the pattern of bits one place
+ to the left produces a number that is twice the value of the
+ previous number.
+
+ Shifting a pattern of bits two places to the left produces results
+ like this (with 8-bit binary numbers):
+
+ (lsh 3 2)
+ => 12
+ ;; Decimal 3 becomes decimal 12.
+ 00000011 => 00001100
+
+ On the other hand, shifting one place to the right looks like this:
+
+ (lsh 6 -1)
+ => 3
+ ;; Decimal 6 becomes decimal 3.
+ 00000110 => 00000011
+
+ (lsh 5 -1)
+ => 2
+ ;; Decimal 5 becomes decimal 2.
+ 00000101 => 00000010
+
+ As the example illustrates, shifting one place to the right
+ divides the value of a positive integer by two, rounding downward.
+
+ The function `lsh', like all XEmacs Lisp arithmetic functions, does
+ not check for overflow, so shifting left can discard significant
+ bits and change the sign of the number. For example, left shifting
+ 134,217,727 produces -2 on a 28-bit machine:
+
+ (lsh 134217727 1) ; left shift
+ => -2
+
+ In binary, in the 28-bit implementation, the argument looks like
+ this:
+
+ ;; Decimal 134,217,727
+ 0111 1111 1111 1111 1111 1111 1111
+
+ which becomes the following when left shifted:
+
+ ;; Decimal -2
+ 1111 1111 1111 1111 1111 1111 1110
+
+ - Function: ash integer1 count
+ `ash' ("arithmetic shift") shifts the bits in INTEGER1 to the left
+ COUNT places, or to the right if COUNT is negative.
+
+ `ash' gives the same results as `lsh' except when INTEGER1 and
+ COUNT are both negative. In that case, `ash' puts ones in the
+ empty bit positions on the left, while `lsh' puts zeros in those
+ bit positions.
+
+ Thus, with `ash', shifting the pattern of bits one place to the
+ right looks like this:
+
+ (ash -6 -1) => -3
+ ;; Decimal -6 becomes decimal -3.
+ 1111 1111 1111 1111 1111 1111 1010
+ =>
+ 1111 1111 1111 1111 1111 1111 1101
+
+ In contrast, shifting the pattern of bits one place to the right
+ with `lsh' looks like this:
+
+ (lsh -6 -1) => 134217725
+ ;; Decimal -6 becomes decimal 134,217,725.
+ 1111 1111 1111 1111 1111 1111 1010
+ =>
+ 0111 1111 1111 1111 1111 1111 1101
+
+ Here are other examples:
+
+ ; 28-bit binary values
+
+ (lsh 5 2) ; 5 = 0000 0000 0000 0000 0000 0000 0101
+ => 20 ; = 0000 0000 0000 0000 0000 0001 0100
+ (ash 5 2)
+ => 20
+ (lsh -5 2) ; -5 = 1111 1111 1111 1111 1111 1111 1011
+ => -20 ; = 1111 1111 1111 1111 1111 1110 1100
+ (ash -5 2)
+ => -20
+ (lsh 5 -2) ; 5 = 0000 0000 0000 0000 0000 0000 0101
+ => 1 ; = 0000 0000 0000 0000 0000 0000 0001
+ (ash 5 -2)
+ => 1
+ (lsh -5 -2) ; -5 = 1111 1111 1111 1111 1111 1111 1011
+ => 4194302 ; = 0011 1111 1111 1111 1111 1111 1110
+ (ash -5 -2) ; -5 = 1111 1111 1111 1111 1111 1111 1011
+ => -2 ; = 1111 1111 1111 1111 1111 1111 1110
+
+ - Function: logand &rest ints-or-markers
+ This function returns the "logical and" of the arguments: the Nth
+ bit is set in the result if, and only if, the Nth bit is set in
+ all the arguments. ("Set" means that the value of the bit is 1
+ rather than 0.)
+
+ For example, using 4-bit binary numbers, the "logical and" of 13
+ and 12 is 12: 1101 combined with 1100 produces 1100. In both the
+ binary numbers, the leftmost two bits are set (i.e., they are
+ 1's), so the leftmost two bits of the returned value are set.
+ However, for the rightmost two bits, each is zero in at least one
+ of the arguments, so the rightmost two bits of the returned value
+ are 0's.
+
+ Therefore,
+
+ (logand 13 12)
+ => 12
+
+ If `logand' is not passed any argument, it returns a value of -1.
+ This number is an identity element for `logand' because its binary
+ representation consists entirely of ones. If `logand' is passed
+ just one argument, it returns that argument.
+
+ ; 28-bit binary values
+
+ (logand 14 13) ; 14 = 0000 0000 0000 0000 0000 0000 1110
+ ; 13 = 0000 0000 0000 0000 0000 0000 1101
+ => 12 ; 12 = 0000 0000 0000 0000 0000 0000 1100
+
+ (logand 14 13 4) ; 14 = 0000 0000 0000 0000 0000 0000 1110
+ ; 13 = 0000 0000 0000 0000 0000 0000 1101
+ ; 4 = 0000 0000 0000 0000 0000 0000 0100
+ => 4 ; 4 = 0000 0000 0000 0000 0000 0000 0100
+
+ (logand)
+ => -1 ; -1 = 1111 1111 1111 1111 1111 1111 1111
+
+ - Function: logior &rest ints-or-markers
+ This function returns the "inclusive or" of its arguments: the Nth
+ bit is set in the result if, and only if, the Nth bit is set in at
+ least one of the arguments. If there are no arguments, the result
+ is zero, which is an identity element for this operation. If
+ `logior' is passed just one argument, it returns that argument.
+
+ ; 28-bit binary values
+
+ (logior 12 5) ; 12 = 0000 0000 0000 0000 0000 0000 1100
+ ; 5 = 0000 0000 0000 0000 0000 0000 0101
+ => 13 ; 13 = 0000 0000 0000 0000 0000 0000 1101
+
+ (logior 12 5 7) ; 12 = 0000 0000 0000 0000 0000 0000 1100
+ ; 5 = 0000 0000 0000 0000 0000 0000 0101
+ ; 7 = 0000 0000 0000 0000 0000 0000 0111
+ => 15 ; 15 = 0000 0000 0000 0000 0000 0000 1111
+
+ - Function: logxor &rest ints-or-markers
+ This function returns the "exclusive or" of its arguments: the Nth
+ bit is set in the result if, and only if, the Nth bit is set in an
+ odd number of the arguments. If there are no arguments, the
+ result is 0, which is an identity element for this operation. If
+ `logxor' is passed just one argument, it returns that argument.
+
+ ; 28-bit binary values
+
+ (logxor 12 5) ; 12 = 0000 0000 0000 0000 0000 0000 1100
+ ; 5 = 0000 0000 0000 0000 0000 0000 0101
+ => 9 ; 9 = 0000 0000 0000 0000 0000 0000 1001
+
+ (logxor 12 5 7) ; 12 = 0000 0000 0000 0000 0000 0000 1100
+ ; 5 = 0000 0000 0000 0000 0000 0000 0101
+ ; 7 = 0000 0000 0000 0000 0000 0000 0111
+ => 14 ; 14 = 0000 0000 0000 0000 0000 0000 1110
+
+ - Function: lognot integer
+ This function returns the logical complement of its argument: the
+ Nth bit is one in the result if, and only if, the Nth bit is zero
+ in INTEGER, and vice-versa.
+
+ (lognot 5)
+ => -6
+ ;; 5 = 0000 0000 0000 0000 0000 0000 0101
+ ;; becomes
+ ;; -6 = 1111 1111 1111 1111 1111 1111 1010
+
+\1f
+File: lispref.info, Node: Math Functions, Next: Random Numbers, Prev: Bitwise Operations, Up: Numbers
+
+Standard Mathematical Functions
+===============================
+
+These mathematical functions are available if floating point is
+supported (which is the normal state of affairs). They allow integers
+as well as floating point numbers as arguments.
+
+ - Function: sin number
+ - Function: cos number
+ - Function: tan number
+ These are the ordinary trigonometric functions, with argument
+ measured in radians.
+
+ - Function: asin number
+ The value of `(asin NUMBER)' is a number between -pi/2 and pi/2
+ (inclusive) whose sine is NUMBER; if, however, NUMBER is out of
+ range (outside [-1, 1]), then the result is a NaN.
+
+ - Function: acos number
+ The value of `(acos NUMBER)' is a number between 0 and pi
+ (inclusive) whose cosine is NUMBER; if, however, NUMBER is out of
+ range (outside [-1, 1]), then the result is a NaN.
+
+ - Function: atan number &optional number2
+ The value of `(atan NUMBER)' is a number between -pi/2 and pi/2
+ (exclusive) whose tangent is NUMBER.
+
+ If optional argument NUMBER2 is supplied, the function returns
+ `atan2(NUMBER,NUMBER2)'.
+
+ - Function: sinh number
+ - Function: cosh number
+ - Function: tanh number
+ These are the ordinary hyperbolic trigonometric functions.
+
+ - Function: asinh number
+ - Function: acosh number
+ - Function: atanh number
+ These are the inverse hyperbolic trigonometric functions.
+
+ - Function: exp number
+ This is the exponential function; it returns e to the power
+ NUMBER. e is a fundamental mathematical constant also called the
+ base of natural logarithms.
+
+ - Function: log number &optional base
+ This function returns the logarithm of NUMBER, with base BASE. If
+ you don't specify BASE, the base `e' is used. If NUMBER is
+ negative, the result is a NaN.
+
+ - Function: log10 number
+ This function returns the logarithm of NUMBER, with base 10. If
+ NUMBER is negative, the result is a NaN. `(log10 X)' == `(log X
+ 10)', at least approximately.
+
+ - Function: expt x y
+ This function returns X raised to power Y. If both arguments are
+ integers and Y is positive, the result is an integer; in this
+ case, it is truncated to fit the range of possible integer values.
+
+ - Function: sqrt number
+ This returns the square root of NUMBER. If NUMBER is negative,
+ the value is a NaN.
+
+ - Function: cube-root number
+ This returns the cube root of NUMBER.
+
+\1f
+File: lispref.info, Node: Random Numbers, Prev: Math Functions, Up: Numbers
+
+Random Numbers
+==============
+
+A deterministic computer program cannot generate true random numbers.
+For most purposes, "pseudo-random numbers" suffice. A series of
+pseudo-random numbers is generated in a deterministic fashion. The
+numbers are not truly random, but they have certain properties that
+mimic a random series. For example, all possible values occur equally
+often in a pseudo-random series.
+
+ In XEmacs, pseudo-random numbers are generated from a "seed" number.
+Starting from any given seed, the `random' function always generates
+the same sequence of numbers. XEmacs always starts with the same seed
+value, so the sequence of values of `random' is actually the same in
+each XEmacs run! For example, in one operating system, the first call
+to `(random)' after you start XEmacs always returns -1457731, and the
+second one always returns -7692030. This repeatability is helpful for
+debugging.
+
+ If you want truly unpredictable random numbers, execute `(random
+t)'. This chooses a new seed based on the current time of day and on
+XEmacs's process ID number.
+
+ - Function: random &optional limit
+ This function returns a pseudo-random integer. Repeated calls
+ return a series of pseudo-random integers.
+
+ If LIMIT is a positive integer, the value is chosen to be
+ nonnegative and less than LIMIT.
+
+ If LIMIT is `t', it means to choose a new seed based on the
+ current time of day and on XEmacs's process ID number.
+
+ On some machines, any integer representable in Lisp may be the
+ result of `random'. On other machines, the result can never be
+ larger than a certain maximum or less than a certain (negative)
+ minimum.
+
+\1f
+File: lispref.info, Node: Strings and Characters, Next: Lists, Prev: Numbers, Up: Top
+
+Strings and Characters
+**********************
+
+A string in XEmacs Lisp is an array that contains an ordered sequence
+of characters. Strings are used as names of symbols, buffers, and
+files, to send messages to users, to hold text being copied between
+buffers, and for many other purposes. Because strings are so important,
+XEmacs Lisp has many functions expressly for manipulating them. XEmacs
+Lisp programs use strings more often than individual characters.
+
+* Menu:
+
+* String Basics:: Basic properties of strings and characters.
+* Predicates for Strings:: Testing whether an object is a string or char.
+* Creating Strings:: Functions to allocate new strings.
+* Predicates for Characters:: Testing whether an object is a character.
+* Character Codes:: Each character has an equivalent integer.
+* Text Comparison:: Comparing characters or strings.
+* String Conversion:: Converting characters or strings and vice versa.
+* Modifying Strings:: Changing characters in a string.
+* String Properties:: Additional information attached to strings.
+* Formatting Strings:: `format': XEmacs's analog of `printf'.
+* Character Case:: Case conversion functions.
+* Case Tables:: Customizing case conversion.
+* Char Tables:: Mapping from characters to Lisp objects.
+
+\1f
+File: lispref.info, Node: String Basics, Next: Predicates for Strings, Up: Strings and Characters
+
+String and Character Basics
+===========================
+
+Strings in XEmacs Lisp are arrays that contain an ordered sequence of
+characters. Characters are their own primitive object type in XEmacs
+20. However, in XEmacs 19, characters are represented in XEmacs Lisp as
+integers; whether an integer was intended as a character or not is
+determined only by how it is used. *Note Character Type::.
+
+ The length of a string (like any array) is fixed and independent of
+the string contents, and cannot be altered. Strings in Lisp are _not_
+terminated by a distinguished character code. (By contrast, strings in
+C are terminated by a character with ASCII code 0.) This means that
+any character, including the null character (ASCII code 0), is a valid
+element of a string.
+
+ Since strings are considered arrays, you can operate on them with the
+general array functions. (*Note Sequences Arrays Vectors::.) For
+example, you can access or change individual characters in a string
+using the functions `aref' and `aset' (*note Array Functions::).
+
+ Strings use an efficient representation for storing the characters
+in them, and thus take up much less memory than a vector of the same
+length.
+
+ Sometimes you will see strings used to hold key sequences. This
+exists for backward compatibility with Emacs 18, but should _not_ be
+used in new code, since many key chords can't be represented at all and
+others (in particular meta key chords) are confused with accented
+characters.
+
+ Strings are useful for holding regular expressions. You can also
+match regular expressions against strings (*note Regexp Search::). The
+functions `match-string' (*note Simple Match Data::) and
+`replace-match' (*note Replacing Match::) are useful for decomposing
+and modifying strings based on regular expression matching.
+
+ Like a buffer, a string can contain extents in it. These extents are
+created when a function such as `buffer-substring' is called on a
+region with duplicable extents in it. When the string is inserted into
+a buffer, the extents are inserted along with it. *Note Duplicable
+Extents::.
+
+ *Note Text::, for information about functions that display strings or
+copy them into buffers. *Note Character Type::, and *Note String
+Type::, for information about the syntax of characters and strings.
+
+\1f
+File: lispref.info, Node: Predicates for Strings, Next: Creating Strings, Prev: String Basics, Up: Strings and Characters
+
+The Predicates for Strings
+==========================
+
+For more information about general sequence and array predicates, see
+*Note Sequences Arrays Vectors::, and *Note Arrays::.
+
+ - Function: stringp object
+ This function returns `t' if OBJECT is a string, `nil' otherwise.
+
+ - Function: char-or-string-p object
+ This function returns `t' if OBJECT is a string or a character,
+ `nil' otherwise.
+
+ In XEmacs addition, this function also returns `t' if OBJECT is an
+ integer that can be represented as a character. This is because
+ of compatibility with previous XEmacs and should not be depended
+ on.
+
+\1f
+File: lispref.info, Node: Creating Strings, Next: Predicates for Characters, Prev: Predicates for Strings, Up: Strings and Characters
+
+Creating Strings
+================
+
+The following functions create strings, either from scratch, or by
+putting strings together, or by taking them apart.
+
+ - Function: string &rest characters
+ This function returns a new string made up of CHARACTERS.
+
+ (string ?X ?E ?m ?a ?c ?s)
+ => "XEmacs"
+ (string)
+ => ""
+
+ Analogous functions operating on other data types include `list',
+ `cons' (*note Building Lists::), `vector' (*note Vectors::) and
+ `bit-vector' (*note Bit Vectors::). This function has not been
+ available in XEmacs prior to 21.0 and FSF Emacs prior to 20.3.
+
+ - Function: make-string length character
+ This function returns a new string consisting entirely of LENGTH
+ successive copies of CHARACTER. LENGTH must be a non-negative
+ integer.
+
+ (make-string 5 ?x)
+ => "xxxxx"
+ (make-string 0 ?x)
+ => ""
+
+ Other functions to compare with this one include `char-to-string'
+ (*note String Conversion::), `make-vector' (*note Vectors::), and
+ `make-list' (*note Building Lists::).
+
+ - Function: substring string start &optional end
+ This function returns a new string which consists of those
+ characters from STRING in the range from (and including) the
+ character at the index START up to (but excluding) the character
+ at the index END. The first character is at index zero.
+
+ (substring "abcdefg" 0 3)
+ => "abc"
+
+ Here the index for `a' is 0, the index for `b' is 1, and the index
+ for `c' is 2. Thus, three letters, `abc', are copied from the
+ string `"abcdefg"'. The index 3 marks the character position up
+ to which the substring is copied. The character whose index is 3
+ is actually the fourth character in the string.
+
+ A negative number counts from the end of the string, so that -1
+ signifies the index of the last character of the string. For
+ example:
+
+ (substring "abcdefg" -3 -1)
+ => "ef"
+
+ In this example, the index for `e' is -3, the index for `f' is -2,
+ and the index for `g' is -1. Therefore, `e' and `f' are included,
+ and `g' is excluded.
+
+ When `nil' is used as an index, it stands for the length of the
+ string. Thus,
+
+ (substring "abcdefg" -3 nil)
+ => "efg"
+
+ Omitting the argument END is equivalent to specifying `nil'. It
+ follows that `(substring STRING 0)' returns a copy of all of
+ STRING.
+
+ (substring "abcdefg" 0)
+ => "abcdefg"
+
+ But we recommend `copy-sequence' for this purpose (*note Sequence
+ Functions::).
+
+ If the characters copied from STRING have duplicable extents or
+ text properties, those are copied into the new string also. *Note
+ Duplicable Extents::.
+
+ A `wrong-type-argument' error is signaled if either START or END
+ is not an integer or `nil'. An `args-out-of-range' error is
+ signaled if START indicates a character following END, or if
+ either integer is out of range for STRING.
+
+ Contrast this function with `buffer-substring' (*note Buffer
+ Contents::), which returns a string containing a portion of the
+ text in the current buffer. The beginning of a string is at index
+ 0, but the beginning of a buffer is at index 1.
+
+ - Function: concat &rest sequences
+ This function returns a new string consisting of the characters in
+ the arguments passed to it (along with their text properties, if
+ any). The arguments may be strings, lists of numbers, or vectors
+ of numbers; they are not themselves changed. If `concat' receives
+ no arguments, it returns an empty string.
+
+ (concat "abc" "-def")
+ => "abc-def"
+ (concat "abc" (list 120 (+ 256 121)) [122])
+ => "abcxyz"
+ ;; `nil' is an empty sequence.
+ (concat "abc" nil "-def")
+ => "abc-def"
+ (concat "The " "quick brown " "fox.")
+ => "The quick brown fox."
+ (concat)
+ => ""
+
+ The second example above shows how characters stored in strings are
+ taken modulo 256. In other words, each character in the string is
+ stored in one byte.
+
+ The `concat' function always constructs a new string that is not
+ `eq' to any existing string.
+
+ When an argument is an integer (not a sequence of integers), it is
+ converted to a string of digits making up the decimal printed
+ representation of the integer. *Don't use this feature; we plan
+ to eliminate it. If you already use this feature, change your
+ programs now!* The proper way to convert an integer to a decimal
+ number in this way is with `format' (*note Formatting Strings::) or
+ `number-to-string' (*note String Conversion::).
+
+ (concat 137)
+ => "137"
+ (concat 54 321)
+ => "54321"
+
+ For information about other concatenation functions, see the
+ description of `mapconcat' in *Note Mapping Functions::, `vconcat'
+ in *Note Vectors::, `bvconcat' in *Note Bit Vectors::, and `append'
+ in *Note Building Lists::.
+
+\1f
+File: lispref.info, Node: Predicates for Characters, Next: Character Codes, Prev: Creating Strings, Up: Strings and Characters
+
+The Predicates for Characters
+=============================
+
+ - Function: characterp object
+ This function returns `t' if OBJECT is a character.
+
+ Some functions that work on integers (e.g. the comparison functions
+ <, <=, =, /=, etc. and the arithmetic functions +, -, *, etc.)
+ accept characters and implicitly convert them into integers. In
+ general, functions that work on characters also accept char-ints
+ and implicitly convert them into characters. WARNING: Neither of
+ these behaviors is very desirable, and they are maintained for
+ backward compatibility with old E-Lisp programs that confounded
+ characters and integers willy-nilly. These behaviors may change
+ in the future; therefore, do not rely on them. Instead, convert
+ the characters explicitly using `char-int'.
+
+ - Function: integer-or-char-p object
+ This function returns `t' if OBJECT is an integer or character.
+
+\1f
+File: lispref.info, Node: Character Codes, Next: Text Comparison, Prev: Predicates for Characters, Up: Strings and Characters
+
+Character Codes
+===============
+
+ - Function: char-int character
+ This function converts a character into an equivalent integer.
+ The resulting integer will always be non-negative. The integers in
+ the range 0 - 255 map to characters as follows:
+
+ 0 - 31
+ Control set 0
+
+ 32 - 127
+ ASCII
+
+ 128 - 159
+ Control set 1
+
+ 160 - 255
+ Right half of ISO-8859-1
+
+ If support for MULE does not exist, these are the only valid
+ character values. When MULE support exists, the values assigned to
+ other characters may vary depending on the particular version of
+ XEmacs, the order in which character sets were loaded, etc., and
+ you should not depend on them.
+
+ - Function: int-char integer
+ This function converts an integer into the equivalent character.
+ Not all integers correspond to valid characters; use `char-int-p'
+ to determine whether this is the case. If the integer cannot be
+ converted, `nil' is returned.
+
+ - Function: char-int-p object
+ This function returns `t' if OBJECT is an integer that can be
+ converted into a character.
+
+ - Function: char-or-char-int-p object
+ This function returns `t' if OBJECT is a character or an integer
+ that can be converted into one.
+
+\1f
+File: lispref.info, Node: Text Comparison, Next: String Conversion, Prev: Character Codes, Up: Strings and Characters
+
+Comparison of Characters and Strings
+====================================
+
+ - Function: char-equal character1 character2 &optional buffer
+ This function returns `t' if the arguments represent the same
+ character, `nil' otherwise. This function ignores differences in
+ case if the value of `case-fold-search' is non-`nil' in BUFFER,
+ which defaults to the current buffer.
+
+ (char-equal ?x ?x)
+ => t
+ (let ((case-fold-search t))
+ (char-equal ?x ?X))
+ => t
+ (let ((case-fold-search nil))
+ (char-equal ?x ?X))
+ => nil
+
+ - Function: char= character1 character2
+ This function returns `t' if the arguments represent the same
+ character, `nil' otherwise. Case is significant.
+
+ (char= ?x ?x)
+ => t
+ (char= ?x ?X)
+ => nil
+ (let ((case-fold-search t))
+ (char-equal ?x ?X))
+ => nil
+ (let ((case-fold-search nil))
+ (char-equal ?x ?X))
+ => nil
+
+ - Function: string= string1 string2
+ This function returns `t' if the characters of the two strings
+ match exactly; case is significant.
+
+ (string= "abc" "abc")
+ => t
+ (string= "abc" "ABC")
+ => nil
+ (string= "ab" "ABC")
+ => nil
+
+
+ - Function: string-equal string1 string2
+ `string-equal' is another name for `string='.
+
+ - Function: string< string1 string2
+ This function compares two strings a character at a time. First it
+ scans both the strings at once to find the first pair of
+ corresponding characters that do not match. If the lesser
+ character of those two is the character from STRING1, then STRING1
+ is less, and this function returns `t'. If the lesser character
+ is the one from STRING2, then STRING1 is greater, and this
+ function returns `nil'. If the two strings match entirely, the
+ value is `nil'.
+
+ Pairs of characters are compared by their ASCII codes. Keep in
+ mind that lower case letters have higher numeric values in the
+ ASCII character set than their upper case counterparts; numbers and
+ many punctuation characters have a lower numeric value than upper
+ case letters.
+
+ (string< "abc" "abd")
+ => t
+ (string< "abd" "abc")
+ => nil
+ (string< "123" "abc")
+ => t
+
+ When the strings have different lengths, and they match up to the
+ length of STRING1, then the result is `t'. If they match up to
+ the length of STRING2, the result is `nil'. A string of no
+ characters is less than any other string.
+
+ (string< "" "abc")
+ => t
+ (string< "ab" "abc")
+ => t
+ (string< "abc" "")
+ => nil
+ (string< "abc" "ab")
+ => nil
+ (string< "" "")
+ => nil
+
+ - Function: string-lessp string1 string2
+ `string-lessp' is another name for `string<'.
+
+ See also `compare-buffer-substrings' in *Note Comparing Text::, for
+a way to compare text in buffers. The function `string-match', which
+matches a regular expression against a string, can be used for a kind
+of string comparison; see *Note Regexp Search::.
+
+\1f
+File: lispref.info, Node: String Conversion, Next: Modifying Strings, Prev: Text Comparison, Up: Strings and Characters
+
+Conversion of Characters and Strings
+====================================
+
+This section describes functions for conversions between characters,
+strings and integers. `format' and `prin1-to-string' (*note Output
+Functions::) can also convert Lisp objects into strings.
+`read-from-string' (*note Input Functions::) can "convert" a string
+representation of a Lisp object into an object.
+
+ *Note Documentation::, for functions that produce textual
+descriptions of text characters and general input events
+(`single-key-description' and `text-char-description'). These
+functions are used primarily for making help messages.
+
+ - Function: char-to-string character
+ This function returns a new string with a length of one character.
+ The value of CHARACTER, modulo 256, is used to initialize the
+ element of the string.
+
+ This function is similar to `make-string' with an integer argument
+ of 1. (*Note Creating Strings::.) This conversion can also be
+ done with `format' using the `%c' format specification. (*Note
+ Formatting Strings::.)
+
+ (char-to-string ?x)
+ => "x"
+ (char-to-string (+ 256 ?x))
+ => "x"
+ (make-string 1 ?x)
+ => "x"
+
+ - Function: string-to-char string
+ This function returns the first character in STRING. If the
+ string is empty, the function returns 0. (Under XEmacs 19, the
+ value is also 0 when the first character of STRING is the null
+ character, ASCII code 0.)
+
+ (string-to-char "ABC")
+ => ?A ;; Under XEmacs 20.
+ => 65 ;; Under XEmacs 19.
+ (string-to-char "xyz")
+ => ?x ;; Under XEmacs 20.
+ => 120 ;; Under XEmacs 19.
+ (string-to-char "")
+ => 0
+ (string-to-char "\000")
+ => ?\^ ;; Under XEmacs 20.
+ => 0 ;; Under XEmacs 20.
+
+ This function may be eliminated in the future if it does not seem
+ useful enough to retain.
+
+ - Function: number-to-string number
+ This function returns a string consisting of the printed
+ representation of NUMBER, which may be an integer or a floating
+ point number. The value starts with a sign if the argument is
+ negative.
+
+ (number-to-string 256)
+ => "256"
+ (number-to-string -23)
+ => "-23"
+ (number-to-string -23.5)
+ => "-23.5"
+
+ `int-to-string' is a semi-obsolete alias for this function.
+
+ See also the function `format' in *Note Formatting Strings::.
+
+ - Function: string-to-number string &optional base
+ This function returns the numeric value represented by STRING,
+ read in BASE. It skips spaces and tabs at the beginning of
+ STRING, then reads as much of STRING as it can interpret as a
+ number. (On some systems it ignores other whitespace at the
+ beginning, not just spaces and tabs.) If the first character
+ after the ignored whitespace is not a digit or a minus sign, this
+ function returns 0.
+
+ If BASE is not specified, it defaults to ten. With BASE other
+ than ten, only integers can be read.
+
+ (string-to-number "256")
+ => 256
+ (string-to-number "25 is a perfect square.")
+ => 25
+ (string-to-number "X256")
+ => 0
+ (string-to-number "-4.5")
+ => -4.5
+ (string-to-number "ffff" 16)
+ => 65535
+
+ `string-to-int' is an obsolete alias for this function.
+
+\1f
+File: lispref.info, Node: Modifying Strings, Next: String Properties, Prev: String Conversion, Up: Strings and Characters
+
+Modifying Strings
+=================
+
+You can modify a string using the general array-modifying primitives.
+*Note Arrays::. The function `aset' modifies a single character; the
+function `fillarray' sets all characters in the string to a specified
+character.
+
+ Each string has a tick counter that starts out at zero (when the
+string is created) and is incremented each time a change is made to that
+string.
+
+ - Function: string-modified-tick string
+ This function returns the tick counter for `string'.
+
+\1f
+File: lispref.info, Node: String Properties, Next: Formatting Strings, Prev: Modifying Strings, Up: Strings and Characters
+
+String Properties
+=================
+
+Just as with symbols, extents, faces, and glyphs, you can attach
+additional information to strings in the form of "string properties".
+These differ from text properties, which are logically attached to
+particular characters in the string.
+
+ To attach a property to a string, use `put'. To retrieve a property
+from a string, use `get'. You can also use `remprop' to remove a
+property from a string and `object-plist' to retrieve a list of all the
+properties in a string.
+
+\1f
+File: lispref.info, Node: Formatting Strings, Next: Character Case, Prev: String Properties, Up: Strings and Characters
+
+Formatting Strings
+==================
+
+"Formatting" means constructing a string by substitution of computed
+values at various places in a constant string. This string controls
+how the other values are printed as well as where they appear; it is
+called a "format string".
+
+ Formatting is often useful for computing messages to be displayed.
+In fact, the functions `message' and `error' provide the same
+formatting feature described here; they differ from `format' only in
+how they use the result of formatting.
+
+ - Function: format string &rest objects
+ This function returns a new string that is made by copying STRING
+ and then replacing any format specification in the copy with
+ encodings of the corresponding OBJECTS. The arguments OBJECTS are
+ the computed values to be formatted.
+
+ A format specification is a sequence of characters beginning with a
+`%'. Thus, if there is a `%d' in STRING, the `format' function
+replaces it with the printed representation of one of the values to be
+formatted (one of the arguments OBJECTS). For example:
+
+ (format "The value of fill-column is %d." fill-column)
+ => "The value of fill-column is 72."
+
+ If STRING contains more than one format specification, the format
+specifications correspond with successive values from OBJECTS. Thus,
+the first format specification in STRING uses the first such value, the
+second format specification uses the second such value, and so on. Any
+extra format specifications (those for which there are no corresponding
+values) cause unpredictable behavior. Any extra values to be formatted
+are ignored.
+
+ Certain format specifications require values of particular types.
+However, no error is signaled if the value actually supplied fails to
+have the expected type. Instead, the output is likely to be
+meaningless.
+
+ Here is a table of valid format specifications:
+
+`%s'
+ Replace the specification with the printed representation of the
+ object, made without quoting. Thus, strings are represented by
+ their contents alone, with no `"' characters, and symbols appear
+ without `\' characters. This is equivalent to printing the object
+ with `princ'.
+
+ If there is no corresponding object, the empty string is used.
+
+`%S'
+ Replace the specification with the printed representation of the
+ object, made with quoting. Thus, strings are enclosed in `"'
+ characters, and `\' characters appear where necessary before
+ special characters. This is equivalent to printing the object
+ with `prin1'.
+
+ If there is no corresponding object, the empty string is used.
+
+`%o'
+ Replace the specification with the base-eight representation of an
+ integer.
+
+`%d'
+`%i'
+ Replace the specification with the base-ten representation of an
+ integer.
+
+`%x'
+ Replace the specification with the base-sixteen representation of
+ an integer, using lowercase letters.
+
+`%X'
+ Replace the specification with the base-sixteen representation of
+ an integer, using uppercase letters.
+
+`%c'
+ Replace the specification with the character which is the value
+ given.
+
+`%e'
+ Replace the specification with the exponential notation for a
+ floating point number (e.g. `7.85200e+03').
+
+`%f'
+ Replace the specification with the decimal-point notation for a
+ floating point number.
+
+`%g'
+ Replace the specification with notation for a floating point
+ number, using a "pretty format". Either exponential notation or
+ decimal-point notation will be used (usually whichever is
+ shorter), and trailing zeroes are removed from the fractional part.
+
+`%%'
+ A single `%' is placed in the string. This format specification is
+ unusual in that it does not use a value. For example, `(format "%%
+ %d" 30)' returns `"% 30"'.
+
+ Any other format character results in an `Invalid format operation'
+error.
+
+ Here are several examples:
+
+ (format "The name of this buffer is %s." (buffer-name))
+ => "The name of this buffer is strings.texi."
+
+ (format "The buffer object prints as %s." (current-buffer))
+ => "The buffer object prints as #<buffer strings.texi>."
+
+ (format "The octal value of %d is %o,
+ and the hex value is %x." 18 18 18)
+ => "The octal value of 18 is 22,
+ and the hex value is 12."
+
+ There are many additional flags and specifications that can occur
+between the `%' and the format character, in the following order:
+
+ 1. An optional repositioning specification, which is a positive
+ integer followed by a `$'.
+
+ 2. Zero or more of the optional flag characters `-', `+', ` ', `0',
+ and `#'.
+
+ 3. An asterisk (`*', meaning that the field width is now assumed to
+ have been specified as an argument.
+
+ 4. An optional minimum field width.
+
+ 5. An optional precision, preceded by a `.' character.
+
+ A "repositioning" specification changes which argument to `format'
+is used by the current and all following format specifications.
+Normally the first specification uses the first argument, the second
+specification uses the second argument, etc. Using a repositioning
+specification, you can change this. By placing a number N followed by
+a `$' between the `%' and the format character, you cause the
+specification to use the Nth argument. The next specification will use
+the N+1'th argument, etc.
+
+ For example:
+
+ (format "Can't find file `%s' in directory `%s'."
+ "ignatius.c" "loyola/")
+ => "Can't find file `ignatius.c' in directory `loyola/'."
+
+ (format "In directory `%2$s', the file `%1$s' was not found."
+ "ignatius.c" "loyola/")
+ => "In directory `loyola/', the file `ignatius.c' was not found."
+
+ (format
+ "The numbers %d and %d are %1$x and %x in hex and %1$o and %o in octal."
+ 37 12)
+ => "The numbers 37 and 12 are 25 and c in hex and 45 and 14 in octal."
+
+ As you can see, this lets you reprocess arguments more than once or
+reword a format specification (thereby moving the arguments around)
+without having to actually reorder the arguments. This is especially
+useful in translating messages from one language to another: Different
+languages use different word orders, and this sometimes entails changing
+the order of the arguments. By using repositioning specifications,
+this can be accomplished without having to embed knowledge of particular
+languages into the location in the program's code where the message is
+displayed.
+
+ All the specification characters allow an optional numeric prefix
+between the `%' and the character, and following any repositioning
+specification or flag. The optional numeric prefix defines the minimum
+width for the object. If the printed representation of the object
+contains fewer characters than this, then it is padded. The padding is
+normally on the left, but will be on the right if the `-' flag
+character is given. The padding character is normally a space, but if
+the `0' flag character is given, zeros are used for padding.
+
+ (format "%06d is padded on the left with zeros" 123)
+ => "000123 is padded on the left with zeros"
+
+ (format "%-6d is padded on the right" 123)
+ => "123 is padded on the right"
+
+ `format' never truncates an object's printed representation, no
+matter what width you specify. Thus, you can use a numeric prefix to
+specify a minimum spacing between columns with no risk of losing
+information.
+
+ In the following three examples, `%7s' specifies a minimum width of
+7. In the first case, the string inserted in place of `%7s' has only 3
+letters, so 4 blank spaces are inserted for padding. In the second
+case, the string `"specification"' is 13 letters wide but is not
+truncated. In the third case, the padding is on the right.
+
+ (format "The word `%7s' actually has %d letters in it."
+ "foo" (length "foo"))
+ => "The word ` foo' actually has 3 letters in it."
+
+ (format "The word `%7s' actually has %d letters in it."
+ "specification" (length "specification"))
+ => "The word `specification' actually has 13 letters in it."
+
+ (format "The word `%-7s' actually has %d letters in it."
+ "foo" (length "foo"))
+ => "The word `foo ' actually has 3 letters in it."
+
+ After any minimum field width, a precision may be specified by
+preceding it with a `.' character. The precision specifies the minimum
+number of digits to appear in `%d', `%i', `%o', `%x', and `%X'
+conversions (the number is padded on the left with zeroes as
+necessary); the number of digits printed after the decimal point for
+`%f', `%e', and `%E' conversions; the number of significant digits
+printed in `%g' and `%G' conversions; and the maximum number of
+non-padding characters printed in `%s' and `%S' conversions. The
+default precision for floating-point conversions is six.
+
+ The other flag characters have the following meanings:
+
+ * The ` ' flag means prefix non-negative numbers with a space.
+
+ * The `+' flag means prefix non-negative numbers with a plus sign.
+
+ * The `#' flag means print numbers in an alternate, more verbose
+ format: octal numbers begin with zero; hex numbers begin with a
+ `0x' or `0X'; a decimal point is printed in `%f', `%e', and `%E'
+ conversions even if no numbers are printed after it; and trailing
+ zeroes are not omitted in `%g' and `%G' conversions.
+
+\1f
+File: lispref.info, Node: Character Case, Next: Case Tables, Prev: Formatting Strings, Up: Strings and Characters
+
+Character Case
+==============
+
+The character case functions change the case of single characters or of
+the contents of strings. The functions convert only alphabetic
+characters (the letters `A' through `Z' and `a' through `z'); other
+characters are not altered. The functions do not modify the strings
+that are passed to them as arguments.
+
+ The examples below use the characters `X' and `x' which have ASCII
+codes 88 and 120 respectively.
+
+ - Function: downcase string-or-char &optional buffer
+ This function converts a character or a string to lower case.
+
+ When the argument to `downcase' is a string, the function creates
+ and returns a new string in which each letter in the argument that
+ is upper case is converted to lower case. When the argument to
+ `downcase' is a character, `downcase' returns the corresponding
+ lower case character. (This value is actually an integer under
+ XEmacs 19.) If the original character is lower case, or is not a
+ letter, then the value equals the original character.
+
+ Optional second arg BUFFER specifies which buffer's case tables to
+ use, and defaults to the current buffer.
+
+ (downcase "The cat in the hat")
+ => "the cat in the hat"
+
+ (downcase ?X)
+ => ?x ;; Under XEmacs 20.
+ => 120 ;; Under XEmacs 19.
+
+ - Function: upcase string-or-char &optional buffer
+ This function converts a character or a string to upper case.
+
+ When the argument to `upcase' is a string, the function creates
+ and returns a new string in which each letter in the argument that
+ is lower case is converted to upper case.
+
+ When the argument to `upcase' is a character, `upcase' returns the
+ corresponding upper case character. (This value is actually an
+ integer under XEmacs 19.) If the original character is upper
+ case, or is not a letter, then the value equals the original
+ character.
+
+ Optional second arg BUFFER specifies which buffer's case tables to
+ use, and defaults to the current buffer.
+
+ (upcase "The cat in the hat")
+ => "THE CAT IN THE HAT"
+
+ (upcase ?x)
+ => ?X ;; Under XEmacs 20.
+ => 88 ;; Under XEmacs 19.
+
+ - Function: capitalize string-or-char &optional buffer
+ This function capitalizes strings or characters. If
+ STRING-OR-CHAR is a string, the function creates and returns a new
+ string, whose contents are a copy of STRING-OR-CHAR in which each
+ word has been capitalized. This means that the first character of
+ each word is converted to upper case, and the rest are converted
+ to lower case.
+
+ The definition of a word is any sequence of consecutive characters
+ that are assigned to the word constituent syntax class in the
+ current syntax table (*note Syntax Class Table::).
+
+ When the argument to `capitalize' is a character, `capitalize' has
+ the same result as `upcase'.
+
+ Optional second arg BUFFER specifies which buffer's case tables to
+ use, and defaults to the current buffer.
+
+ (capitalize "The cat in the hat")
+ => "The Cat In The Hat"
+
+ (capitalize "THE 77TH-HATTED CAT")
+ => "The 77th-Hatted Cat"
+
+ (capitalize ?x)
+ => ?X ;; Under XEmacs 20.
+ => 88 ;; Under XEmacs 19.
+
+\1f
+File: lispref.info, Node: Case Tables, Next: Char Tables, Prev: Character Case, Up: Strings and Characters
+
+The Case Table
+==============
+
+You can customize case conversion by installing a special "case table".
+A case table specifies the mapping between upper case and lower case
+letters. It affects both the string and character case conversion
+functions (see the previous section) and those that apply to text in the
+buffer (*note Case Changes::). You need a case table if you are using a
+language which has letters other than the standard ASCII letters.
+
+ A case table is a list of this form:
+
+ (DOWNCASE UPCASE CANONICALIZE EQUIVALENCES)
+
+where each element is either `nil' or a string of length 256. The
+element DOWNCASE says how to map each character to its lower-case
+equivalent. The element UPCASE maps each character to its upper-case
+equivalent. If lower and upper case characters are in one-to-one
+correspondence, use `nil' for UPCASE; then XEmacs deduces the upcase
+table from DOWNCASE.
+
+ For some languages, upper and lower case letters are not in
+one-to-one correspondence. There may be two different lower case
+letters with the same upper case equivalent. In these cases, you need
+to specify the maps for both directions.
+
+ The element CANONICALIZE maps each character to a canonical
+equivalent; any two characters that are related by case-conversion have
+the same canonical equivalent character.
+
+ The element EQUIVALENCES is a map that cyclicly permutes each
+equivalence class (of characters with the same canonical equivalent).
+(For ordinary ASCII, this would map `a' into `A' and `A' into `a', and
+likewise for each set of equivalent characters.)
+
+ When you construct a case table, you can provide `nil' for
+CANONICALIZE; then Emacs fills in this string from UPCASE and DOWNCASE.
+You can also provide `nil' for EQUIVALENCES; then Emacs fills in this
+string from CANONICALIZE. In a case table that is actually in use,
+those components are non-`nil'. Do not try to specify EQUIVALENCES
+without also specifying CANONICALIZE.
+
+ Each buffer has a case table. XEmacs also has a "standard case
+table" which is copied into each buffer when you create the buffer.
+Changing the standard case table doesn't affect any existing buffers.
+
+ Here are the functions for working with case tables:
+
+ - Function: case-table-p object
+ This predicate returns non-`nil' if OBJECT is a valid case table.
+
+ - Function: set-standard-case-table case-table
+ This function makes CASE-TABLE the standard case table, so that it
+ will apply to any buffers created subsequently.
+
+ - Function: standard-case-table
+ This returns the standard case table.
+
+ - Function: current-case-table &optional buffer
+ This function returns the case table of BUFFER, which defaults to
+ the current buffer.
+
+ - Function: set-case-table case-table
+ This sets the current buffer's case table to CASE-TABLE.
+
+ The following three functions are convenient subroutines for packages
+that define non-ASCII character sets. They modify a string
+DOWNCASE-TABLE provided as an argument; this should be a string to be
+used as the DOWNCASE part of a case table. They also modify the
+standard syntax table. *Note Syntax Tables::.
+
+ - Function: set-case-syntax-pair uc lc downcase-table
+ This function specifies a pair of corresponding letters, one upper
+ case and one lower case.
+
+ - Function: set-case-syntax-delims l r downcase-table
+ This function makes characters L and R a matching pair of
+ case-invariant delimiters.
+
+ - Function: set-case-syntax char syntax downcase-table
+ This function makes CHAR case-invariant, with syntax SYNTAX.
+
+ - Command: describe-buffer-case-table
+ This command displays a description of the contents of the current
+ buffer's case table.
+
+ You can load the library `iso-syntax' to set up the standard syntax
+table and define a case table for the 8-bit ISO Latin 1 character set.
+
+\1f
+File: lispref.info, Node: Char Tables, Prev: Case Tables, Up: Strings and Characters
+
+The Char Table
+==============
+
+A char table is a table that maps characters (or ranges of characters)
+to values. Char tables are specialized for characters, only allowing
+particular sorts of ranges to be assigned values. Although this loses
+in generality, it makes for extremely fast (constant-time) lookups, and
+thus is feasible for applications that do an extremely large number of
+lookups (e.g. scanning a buffer for a character in a particular syntax,
+where a lookup in the syntax table must occur once per character).
+
+ Note that char tables as a primitive type, and all of the functions
+in this section, exist only in XEmacs 20. In XEmacs 19, char tables are
+generally implemented using a vector of 256 elements.
+
+ When MULE support exists, the types of ranges that can be assigned
+values are
+
+ * all characters
+
+ * an entire charset
+
+ * a single row in a two-octet charset
+
+ * a single character
+
+ When MULE support is not present, the types of ranges that can be
+assigned values are
+
+ * all characters
+
+ * a single character
+
+ - Function: char-table-p object
+ This function returns non-`nil' if OBJECT is a char table.
+
+* Menu:
+
+* Char Table Types:: Char tables have different uses.
+* Working With Char Tables:: Creating and working with char tables.
+
+\1f
+File: lispref.info, Node: Char Table Types, Next: Working With Char Tables, Up: Char Tables
+
+Char Table Types
+----------------
+
+Each char table type is used for a different purpose and allows
+different sorts of values. The different char table types are
+
+`category'
+ Used for category tables, which specify the regexp categories that
+ a character is in. The valid values are `nil' or a bit vector of
+ 95 elements. Higher-level Lisp functions are provided for working
+ with category tables. Currently categories and category tables
+ only exist when MULE support is present.
+
+`char'
+ A generalized char table, for mapping from one character to
+ another. Used for case tables, syntax matching tables,
+ `keyboard-translate-table', etc. The valid values are characters.
+
+`generic'
+ An even more generalized char table, for mapping from a character
+ to anything.
+
+`display'
+ Used for display tables, which specify how a particular character
+ is to appear when displayed. #### Not yet implemented.
+
+`syntax'
+ Used for syntax tables, which specify the syntax of a particular
+ character. Higher-level Lisp functions are provided for working
+ with syntax tables. The valid values are integers.
+
+ - Function: char-table-type char-table
+ This function returns the type of char table CHAR-TABLE.
+
+ - Function: char-table-type-list
+ This function returns a list of the recognized char table types.
+
+ - Function: valid-char-table-type-p type
+ This function returns `t' if TYPE if a recognized char table type.
+
+\1f
+File: lispref.info, Node: Working With Char Tables, Prev: Char Table Types, Up: Char Tables
+
+Working With Char Tables
+------------------------
+
+ - Function: make-char-table type
+ This function makes a new, empty char table of type TYPE. TYPE
+ should be a symbol, one of `char', `category', `display',
+ `generic', or `syntax'.
+
+ - Function: put-char-table range value char-table
+ This function sets the value for chars in RANGE to be VALUE in
+ CHAR-TABLE.
+
+ RANGE specifies one or more characters to be affected and should be
+ one of the following:
+
+ * `t' (all characters are affected)
+
+ * A charset (only allowed when MULE support is present)
+
+ * A vector of two elements: a two-octet charset and a row number
+ (only allowed when MULE support is present)
+
+ * A single character
+
+ VALUE must be a value appropriate for the type of CHAR-TABLE.
+
+ - Function: get-char-table character char-table
+ This function finds the value for CHARACTER in CHAR-TABLE.
+
+ - Function: get-range-char-table range char-table &optional multi
+ This function finds the value for a range in CHAR-TABLE. If there
+ is more than one value, MULTI is returned (defaults to `nil').
+
+ - Function: reset-char-table char-table
+ This function resets CHAR-TABLE to its default state.
+
+ - Function: map-char-table function char-table &optional range
+ This function maps FUNCTION over entries in CHAR-TABLE, calling it
+ with two args, each key and value in the table.
+
+ RANGE specifies a subrange to map over and is in the same format
+ as the RANGE argument to `put-range-table'. If omitted or `t', it
+ defaults to the entire table.
+
+ - Function: valid-char-table-value-p value char-table-type
+ This function returns non-`nil' if VALUE is a valid value for
+ CHAR-TABLE-TYPE.
+
+ - Function: check-valid-char-table-value value char-table-type
+ This function signals an error if VALUE is not a valid value for
+ CHAR-TABLE-TYPE.
+
+\1f
+File: lispref.info, Node: Lists, Next: Sequences Arrays Vectors, Prev: Strings and Characters, Up: Top
+
+Lists
+*****
+
+A "list" represents a sequence of zero or more elements (which may be
+any Lisp objects). The important difference between lists and vectors
+is that two or more lists can share part of their structure; in
+addition, you can insert or delete elements in a list without copying
+the whole list.
+
+* Menu:
+
+* Cons Cells:: How lists are made out of cons cells.
+* Lists as Boxes:: Graphical notation to explain lists.
+* List-related Predicates:: Is this object a list? Comparing two lists.
+* List Elements:: Extracting the pieces of a list.
+* Building Lists:: Creating list structure.
+* Modifying Lists:: Storing new pieces into an existing list.
+* Sets And Lists:: A list can represent a finite mathematical set.
+* Association Lists:: A list can represent a finite relation or mapping.
+* Property Lists:: A different way to represent a finite mapping.
+* Weak Lists:: A list with special garbage-collection behavior.
+
+\1f
+File: lispref.info, Node: Cons Cells, Next: Lists as Boxes, Up: Lists
+
+Lists and Cons Cells
+====================
+
+Lists in Lisp are not a primitive data type; they are built up from
+"cons cells". A cons cell is a data object that represents an ordered
+pair. It records two Lisp objects, one labeled as the CAR, and the
+other labeled as the CDR. These names are traditional; see *Note Cons
+Cell Type::. CDR is pronounced "could-er."
+
+ A list is a series of cons cells chained together, one cons cell per
+element of the list. By convention, the CARs of the cons cells are the
+elements of the list, and the CDRs are used to chain the list: the CDR
+of each cons cell is the following cons cell. The CDR of the last cons
+cell is `nil'. This asymmetry between the CAR and the CDR is entirely
+a matter of convention; at the level of cons cells, the CAR and CDR
+slots have the same characteristics.
+
+ Because most cons cells are used as part of lists, the phrase "list
+structure" has come to mean any structure made out of cons cells.
+
+ The symbol `nil' is considered a list as well as a symbol; it is the
+list with no elements. For convenience, the symbol `nil' is considered
+to have `nil' as its CDR (and also as its CAR).
+
+ The CDR of any nonempty list L is a list containing all the elements
+of L except the first.
+
+\1f
+File: lispref.info, Node: Lists as Boxes, Next: List-related Predicates, Prev: Cons Cells, Up: Lists
+
+Lists as Linked Pairs of Boxes
+==============================
+
+A cons cell can be illustrated as a pair of boxes. The first box
+represents the CAR and the second box represents the CDR. Here is an
+illustration of the two-element list, `(tulip lily)', made from two
+cons cells:
+
+ --------------- ---------------
+ | car | cdr | | car | cdr |
+ | tulip | o---------->| lily | nil |
+ | | | | | |
+ --------------- ---------------
+
+ Each pair of boxes represents a cons cell. Each box "refers to",
+"points to" or "contains" a Lisp object. (These terms are synonymous.)
+The first box, which is the CAR of the first cons cell, contains the
+symbol `tulip'. The arrow from the CDR of the first cons cell to the
+second cons cell indicates that the CDR of the first cons cell points
+to the second cons cell.
+
+ The same list can be illustrated in a different sort of box notation
+like this:
+
+ ___ ___ ___ ___
+ |___|___|--> |___|___|--> nil
+ | |
+ | |
+ --> tulip --> lily
+
+ Here is a more complex illustration, showing the three-element list,
+`((pine needles) oak maple)', the first element of which is a
+two-element list:
+
+ ___ ___ ___ ___ ___ ___
+ |___|___|--> |___|___|--> |___|___|--> nil
+ | | |
+ | | |
+ | --> oak --> maple
+ |
+ | ___ ___ ___ ___
+ --> |___|___|--> |___|___|--> nil
+ | |
+ | |
+ --> pine --> needles
+
+ The same list represented in the first box notation looks like this:
+
+ -------------- -------------- --------------
+ | car | cdr | | car | cdr | | car | cdr |
+ | o | o------->| oak | o------->| maple | nil |
+ | | | | | | | | | |
+ -- | --------- -------------- --------------
+ |
+ |
+ | -------------- ----------------
+ | | car | cdr | | car | cdr |
+ ------>| pine | o------->| needles | nil |
+ | | | | | |
+ -------------- ----------------
+
+ *Note Cons Cell Type::, for the read and print syntax of cons cells
+and lists, and for more "box and arrow" illustrations of lists.
+
+\1f
+File: lispref.info, Node: List-related Predicates, Next: List Elements, Prev: Lists as Boxes, Up: Lists
+
+Predicates on Lists
+===================
+
+The following predicates test whether a Lisp object is an atom, is a
+cons cell or is a list, or whether it is the distinguished object
+`nil'. (Many of these predicates can be defined in terms of the
+others, but they are used so often that it is worth having all of them.)
+
+ - Function: consp object
+ This function returns `t' if OBJECT is a cons cell, `nil'
+ otherwise. `nil' is not a cons cell, although it _is_ a list.
+
+ - Function: atom object
+ This function returns `t' if OBJECT is an atom, `nil' otherwise.
+ All objects except cons cells are atoms. The symbol `nil' is an
+ atom and is also a list; it is the only Lisp object that is both.
+
+ (atom OBJECT) == (not (consp OBJECT))
+
+ - Function: listp object
+ This function returns `t' if OBJECT is a cons cell or `nil'.
+ Otherwise, it returns `nil'.
+
+ (listp '(1))
+ => t
+ (listp '())
+ => t
+
+ - Function: nlistp object
+ This function is the opposite of `listp': it returns `t' if OBJECT
+ is not a list. Otherwise, it returns `nil'.
+
+ (listp OBJECT) == (not (nlistp OBJECT))
+
+ - Function: null object
+ This function returns `t' if OBJECT is `nil', and returns `nil'
+ otherwise. This function is identical to `not', but as a matter
+ of clarity we use `null' when OBJECT is considered a list and
+ `not' when it is considered a truth value (see `not' in *Note
+ Combining Conditions::).
+
+ (null '(1))
+ => nil
+ (null '())
+ => t
+
projects / chise / xemacs-chise.git.1 / blobdiff