This is ../info/lispref.info, produced by makeinfo version 4.7 from
lispref/lispref.texi.

INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
* Lispref: (lispref).		XEmacs Lisp Reference Manual.
END-INFO-DIR-ENTRY

   Edition History:

   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998

   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
Copyright (C) 1995, 1996 Ben Wing.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU General Public License" is included
exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice
identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the section entitled "GNU General Public License"
may be included in a translation approved by the Free Software
Foundation instead of in the original English.


File: lispref.info,  Node: Top,  Next: Copying,  Prev: (dir),  Up: (dir)

   This Info file contains the third edition of the XEmacs Lisp
Reference Manual, corresponding to XEmacs version 21.0.

* Menu:

* 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.
* Lists::                   Lists, cons cells, and related functions.
* Sequences Arrays Vectors::  Lists, strings and vectors are called sequences.
                                Certain functions act on any kind of sequence.
                                The description of vectors is here as well.
* Symbols::                 Symbols represent names, uniquely.

* Evaluation::              How Lisp expressions are evaluated.
* Control Structures::      Conditionals, loops, nonlocal exits.
* Variables::               Using symbols in programs to stand for values.

* Functions and Commands::  A function is a Lisp program that can be
                            invoked from other functions.

* Macros::                  Macros are a way to extend the Lisp language.
* Customization::           Writing customization declarations.

* Loading::                 Reading files of Lisp code into Lisp.
* Byte Compilation::        Compilation makes programs run faster.
* Debugging::               Tools and tips for debugging Lisp programs.

* Read and Print::          Converting Lisp objects to text and back.
* Minibuffers::             Using the minibuffer to read input.
* Command Loop::            How the editor command loop works,
                              and how you can call its subroutines.
* Keymaps::                 Defining the bindings from keys to commands.
* Menus::                   Defining pull-down and pop-up menus.
* Dialog Boxes::	    Creating dialog boxes.
* Toolbar::		    Controlling the toolbar.
* Gutter::		    Controlling the gutter.
* Scrollbars::		    Controlling the scrollbars.
* Drag and Drop::	    Generic API to inter-application communication
                              via specific protocols.
* Modes::                   Defining major and minor modes.
* Documentation::           Writing and using documentation strings.

* Files::                   Accessing files.
* Backups and Auto-Saving:: Controlling how backups and auto-save
                              files are made.
* Buffers::                 Creating and using buffer objects.
* Windows::                 Manipulating windows and displaying buffers.
* Frames::		    Making multiple X windows.
* Consoles and Devices::    Opening frames on multiple TTY's or X displays.
* Positions::               Buffer positions and motion functions.
* Markers::                 Markers represent positions and update
                              automatically when the text is changed.

* Text::                    Examining and changing text in buffers.
* Searching and Matching::  Searching buffers for strings or regexps.
* Syntax Tables::           The syntax table controls word and list parsing.
* Abbrevs::                 How Abbrev mode works, and its data structures.

* Extents::                 Extents are regions of text with particular
                              display characteristics.
* Specifiers::		    How faces and glyphs are specified.
* Faces and Window-System Objects::
        		    A face is a set of display characteristics
                              specifying how text is to be displayed.
* Glyphs::		    General interface to pixmaps displayed in a
			      buffer or frame.
* Annotations::             Higher-level interface to glyphs in a buffer.
* Display::	            Parameters controlling screen usage.
                              The bell.  Waiting for input.

* Hash Tables::             Fast data structures for mappings.
* Range Tables::            Keeping track of ranges of numbers.
* Databases::               An interface to standard DBM and DB databases.

* Processes::               Running and communicating with subprocesses.
* System Interface::        Getting the user id, system type, environment
                              variables, and other such things.
* X-Windows::		    Functions specific to the X Window System.
* ToolTalk Support::        Interfacing with the ToolTalk message service.
* LDAP Support::            Interfacing with the Lightweight Directory
                              Access Protocol.
* PostgreSQL Support::      Interfacing to the PostgreSQL libpq library.
* Internationalization::    How Emacs supports different languages and
                              cultural conventions.
* MULE::                    Specifics of the Asian-language support.

Appendices

* Tips::                    Advice for writing Lisp programs.
* Building XEmacs and Object Allocation::
                            Behind-the-scenes information about XEmacs.
* Standard Errors::         List of all error symbols.
* Standard Buffer-Local Variables::  List of variables local in all buffers.
* Standard Keymaps::        List of standard keymaps.
* Standard Hooks::          List of standard hook variables.

* Index::                   Index including concepts, functions, variables,
                              and other terms.

      --- The Detailed Node Listing ---

Here are other nodes that are inferiors of those already listed,
mentioned here so you can get to them in one step:

Introduction

* 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.

Conventions

* 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.

Format of Descriptions

* 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.
* Comments::                Comments and their formatting conventions.
* Programming Types::       Types found in all Lisp systems.
* Editing Types::           Types specific to XEmacs.
* Type Predicates::         Tests related to types.
* Equality Predicates::     Tests of equality between any two objects.

Programming Types

* 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.
* 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.
* Symbol Type::         A multi-use object that refers to a function,
                        variable, property list, or itself.
* 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.

Cons Cell Type

* Dotted Pair Notation::    An alternative syntax for lists.
* Association List Type::   A specially constructed list.

Editing Types

* Buffer Type::             The basic object of editing.
* Window Type::             What makes buffers visible.
* Window Configuration Type:: Save what the screen looks like.
* Marker Type::             A position in a buffer.
* 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.

Numbers

* Integer Basics::            Representation and range of integers.
* Ratio Basics::	      Representation and range of rational numbers.
* Float Basics::	      Representation and range of floating point.
* The Bignum Extension::      Arbitrary precision integers, ratios, and floats.
* Predicates on Numbers::     Testing for numbers.
* Comparison of Numbers::     Equality and inequality predicates.
* Arithmetic Operations::     How to add, subtract, multiply and divide.
* Bitwise Operations::        Logical and, or, not, shifting.
* Numeric Conversions::	      Converting float to integer and vice versa.
* Math Functions::            Trig, exponential and logarithmic functions.
* Random Numbers::            Obtaining random integers, predictable or not.

Strings and Characters

* 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.
* Char Tables::               Mapping from characters to Lisp objects.
* Case Tables::		      Customizing case conversion.

Lists

* 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.

Modifying Existing List Structure

* Setcar::                  Replacing an element in a list.
* Setcdr::                  Replacing part of the list backbone.
                              This can be used to remove or add elements.
* Rearrangement::           Reordering the elements in a list; combining lists.

Sequences, Arrays, and Vectors

* Sequence Functions::      Functions that accept any kind of sequence.
* Arrays::                  Characteristics of arrays in XEmacs Lisp.
* Array Functions::         Functions specifically for arrays.
* Vectors::                 Functions specifically for vectors.

Symbols

* Symbol Components::       Symbols have names, values, function definitions
                              and property lists.
* Definitions::             A definition says how a symbol will be used.
* Creating Symbols::        How symbols are kept unique.
* Symbol Properties::       Each symbol has a property list
                              for recording miscellaneous information.

Evaluation

* Intro Eval::              Evaluation in the scheme of things.
* Eval::                    How to invoke the Lisp interpreter explicitly.
* Forms::                   How various sorts of objects are evaluated.
* Quoting::                 Avoiding evaluation (to put constants in
                              the program).

Kinds of Forms

* Self-Evaluating Forms::   Forms that evaluate to themselves.
* Symbol Forms::            Symbols evaluate as variables.
* Classifying Lists::       How to distinguish various sorts of list forms.
* Function Forms::          Forms that call functions.
* Macro Forms::             Forms that call macros.
* Special Forms::           ``Special forms'' are idiosyncratic primitives,
                              most of them extremely important.
* Autoloading::             Functions set up to load files
                              containing their real definitions.

Control Structures

* Sequencing::              Evaluation in textual order.
* Conditionals::            `if', `cond'.
* Combining Conditions::    `and', `or', `not'.
* Iteration::               `while' loops.
* Nonlocal Exits::          Jumping out of a sequence.

Nonlocal Exits

* Catch and Throw::         Nonlocal exits for the program's own purposes.
* Examples of Catch::       Showing how such nonlocal exits can be written.
* Errors::                  How errors are signaled and handled.
* Cleanups::                Arranging to run a cleanup form if an
                              error happens.

Errors

* Signaling Errors::        How to report an error.
* Processing of Errors::    What XEmacs does when you report an error.
* Handling Errors::         How you can trap errors and continue execution.
* Error Symbols::           How errors are classified for trapping them.

Variables

* Global Variables::        Variable values that exist permanently, everywhere.
* Constant Variables::      Certain "variables" have values that never change.
* Local Variables::         Variable values that exist only temporarily.
* Void Variables::          Symbols that lack values.
* Defining Variables::      A definition says a symbol is used as a variable.
* Accessing Variables::     Examining values of variables whose names
                              are known only at run time.
* Setting Variables::       Storing new values in variables.
* Variable Scoping::        How Lisp chooses among local and global values.
* Buffer-Local Variables::  Variable values in effect only in one buffer.

Scoping Rules for Variable Bindings

* Scope::                   Scope means where in the program a value
                              is visible.  Comparison with other languages.
* Extent::                  Extent means how long in time a value exists.
* Impl of Scope::           Two ways to implement dynamic scoping.
* Using Scoping::           How to use dynamic scoping carefully and
                              avoid problems.

Buffer-Local Variables

* Intro to Buffer-Local::   Introduction and concepts.
* Creating Buffer-Local::   Creating and destroying buffer-local bindings.
* Default Value::           The default value is seen in buffers
                              that don't have their own local values.

Functions

* What Is a Function::      Lisp functions vs primitives; terminology.
* Lambda Expressions::      How functions are expressed as Lisp objects.
* Function Names::          A symbol can serve as the name of a function.
* Defining Functions::      Lisp expressions for defining functions.
* Calling Functions::       How to use an existing function.
* Mapping Functions::       Applying a function to each element of a list, etc.
* Anonymous Functions::     Lambda-expressions are functions with no names.
* Function Cells::          Accessing or setting the function definition
                              of a symbol.
* Related Topics::          Cross-references to specific Lisp primitives
                              that have a special bearing on how
                              functions work.

Lambda Expressions

* Lambda Components::       The parts of a lambda expression.
* Simple Lambda::           A simple example.
* Argument List::           Details and special features of argument lists.
* Function Documentation::  How to put documentation in a function.

Macros

* Simple Macro::            A basic example.
* Expansion::               How, when and why macros are expanded.
* Compiling Macros::        How macros are expanded by the compiler.
* Defining Macros::         How to write a macro definition.
* Backquote::               Easier construction of list structure.
* Problems with Macros::    Don't evaluate the macro arguments too many times.
                              Don't hide the user's variables.

Loading

* How Programs Do Loading:: The `load' function and others.
* Autoload::                Setting up a function to autoload.
* Named Features::          Loading a library if it isn't already loaded.
* Repeated Loading::        Precautions about loading a file twice.

Byte Compilation

* Speed of Byte-Code::          An example of speedup from byte compilation.
* Compilation Functions::       Byte compilation functions.
* Docs and Compilation::        Dynamic loading of documentation strings.
* Dynamic Loading::             Dynamic loading of individual functions.
* Eval During Compile::  	Code to be evaluated when you compile.
* Compiled-Function Objects::	The data type used for byte-compiled functions.
* Disassembly::                 Disassembling byte-code; how to read byte-code.
* Different Behavior::          When compiled code gives different results.

Debugging Lisp Programs

* Debugger::                How the XEmacs Lisp debugger is implemented.
* Syntax Errors::           How to find syntax errors.
* Compilation Errors::      How to find errors that show up in
                              byte compilation.
* Edebug::                  A source-level XEmacs Lisp debugger.

The Lisp Debugger

* Error Debugging::         Entering the debugger when an error happens.
* Function Debugging::      Entering it when a certain function is called.
* Explicit Debug::          Entering it at a certain point in the program.
* Using Debugger::          What the debugger does; what you see while in it.
* Debugger Commands::       Commands used while in the debugger.
* Invoking the Debugger::   How to call the function `debug'.
* Internals of Debugger::   Subroutines of the debugger, and global variables.

Debugging Invalid Lisp Syntax

* Excess Open::             How to find a spurious open paren or missing close.
* Excess Close::            How to find a spurious close paren or missing open.

Reading and Printing Lisp Objects

* Streams Intro::           Overview of streams, reading and printing.
* Input Streams::           Various data types that can be used as
                              input streams.
* Input Functions::         Functions to read Lisp objects from text.
* Output Streams::          Various data types that can be used as
                              output streams.
* Output Functions::        Functions to print Lisp objects as text.

Minibuffers

* Intro to Minibuffers::    Basic information about minibuffers.
* Text from Minibuffer::    How to read a straight text string.
* Object from Minibuffer::  How to read a Lisp object or expression.
* Completion::              How to invoke and customize completion.
* Yes-or-No Queries::       Asking a question with a simple answer.
* Minibuffer Misc::         Various customization hooks and variables.

Completion

* Basic Completion::        Low-level functions for completing strings.
                              (These are too low level to use the minibuffer.)
* Minibuffer Completion::   Invoking the minibuffer with completion.
* Completion Commands::     Minibuffer commands that do completion.
* High-Level Completion::   Convenient special cases of completion
                              (reading buffer name, file name, etc.)
* Reading File Names::      Using completion to read file names.
* Programmed Completion::   Finding the completions for a given file name.

Command Loop

* Command Overview::    How the command loop reads commands.
* Defining Commands::   Specifying how a function should read arguments.
* Interactive Call::    Calling a command, so that it will read arguments.
* Command Loop Info::   Variables set by the command loop for you to examine.
* Events::		What input looks like when you read it.
* Reading Input::       How to read input events from the keyboard or mouse.
* Waiting::             Waiting for user input or elapsed time.
* Quitting::            How C-g works.  How to catch or defer quitting.
* Prefix Command Arguments::    How the commands to set prefix args work.
* Recursive Editing::   Entering a recursive edit,
                          and why you usually shouldn't.
* Disabling Commands::  How the command loop handles disabled commands.
* Command History::     How the command history is set up, and how accessed.
* Keyboard Macros::     How keyboard macros are implemented.

Defining Commands

* Using Interactive::       General rules for `interactive'.
* Interactive Codes::       The standard letter-codes for reading arguments
                              in various ways.
* Interactive Examples::    Examples of how to read interactive arguments.

Events

* Event Types::			Events come in different types.
* Event Contents::		What the contents of each event type are.
* Event Predicates::		Querying whether an event is of a
				  particular type.
* Accessing Mouse Event Positions::
				Determining where a mouse event occurred,
				  and over what.
* Accessing Other Event Info::  Accessing non-positional event info.
* Working With Events::		Creating, copying, and destroying events.
* Converting Events::		Converting between events, keys, and
				  characters.

Accessing Mouse Event Positions

* Frame-Level Event Position Info::
* Window-Level Event Position Info::
* Event Text Position Info::
* Event Glyph Position Info::
* Event Toolbar Position Info::
* Other Event Position Info::

Reading Input

* Key Sequence Input::		How to read one key sequence.
* Reading One Event::		How to read just one event.
* Dispatching an Event::        What to do with an event once it has been read.
* Quoted Character Input::	Asking the user to specify a character.
* Peeking and Discarding::	How to reread or throw away input events.

Keymaps

* Keymap Terminology::        	Definitions of terms pertaining to keymaps.
* Format of Keymaps::		What a keymap looks like as a Lisp object.
* Creating Keymaps:: 		Functions to create and copy keymaps.
* Inheritance and Keymaps::	How one keymap can inherit the bindings
				  of another keymap.
* Key Sequences::               How to specify key sequences.
* Prefix Keys::                 Defining a key with a keymap as its definition.
* Active Keymaps::	        Each buffer has a local keymap
                                  to override the standard (global) bindings.
				Each minor mode can also override them.
* Key Lookup::                  How extracting elements from keymaps works.
* Functions for Key Lookup::    How to request key lookup.
* Changing Key Bindings::       Redefining a key in a keymap.
* Key Binding Commands::        Interactive interfaces for redefining keys.
* Scanning Keymaps::            Looking through all keymaps, for printing help.
* Other Keymap Functions::      Miscellaneous keymap functions.

Menus

* Menu Format::		Format of a menu description.
* Menubar Format::	How to specify a menubar.
* Menubar::		Functions for controlling the menubar.
* Modifying Menus::	Modifying a menu description.
* Pop-Up Menus::	Functions for specifying pop-up menus.
* Menu Filters::	Filter functions for the default menubar.
* Buffers Menu::	The menu that displays the list of buffers.

Dialog Boxes

* Dialog Box Format::
* Dialog Box Functions::

Toolbar

* Toolbar Intro::		An introduction.
* Toolbar Descriptor Format::	How to create a toolbar.
* Specifying the Toolbar::	Setting a toolbar.
* Other Toolbar Variables::	Controlling the size of toolbars.

Gutter

Scrollbars

Major and Minor Modes

* Major Modes::             Defining major modes.
* Minor Modes::             Defining minor modes.
* Modeline Format::         Customizing the text that appears in the modeline.
* Hooks::                   How to use hooks; how to write code that
                              provides hooks.

Major Modes

* Major Mode Conventions::  Coding conventions for keymaps, etc.
* Example Major Modes::     Text mode and Lisp modes.
* Auto Major Mode::         How XEmacs chooses the major mode automatically.
* Mode Help::               Finding out how to use a mode.

Minor Modes

* Minor Mode Conventions::  Tips for writing a minor mode.
* Keymaps and Minor Modes:: How a minor mode can have its own keymap.

Modeline Format

* Modeline Data::           The data structure that controls the modeline.
* Modeline Variables::      Variables used in that data structure.
* %-Constructs::            Putting information into a modeline.

Documentation

* Documentation Basics::    Good style for doc strings.
                              Where to put them.  How XEmacs stores them.
* Accessing Documentation:: How Lisp programs can access doc strings.
* Keys in Documentation::   Substituting current key bindings.
* Describing Characters::   Making printable descriptions of
                              non-printing characters and key sequences.
* Help Functions::          Subroutines used by XEmacs help facilities.

Files

* Visiting Files::          Reading files into Emacs buffers for editing.
* Saving Buffers::          Writing changed buffers back into files.
* Reading from Files::      Reading files into other buffers.
* Writing to Files::        Writing new files from parts of buffers.
* File Locks::              Locking and unlocking files, to prevent
                                simultaneous editing by two people.
* Information about Files::   Testing existence, accessibility, size of files.
* Contents of Directories::   Getting a list of the files in a directory.
* Changing File Attributes::  Renaming files, changing protection, etc.
* File Names::                Decomposing and expanding file names.

Visiting Files

* Visiting Functions::      The usual interface functions for visiting.
* Subroutines of Visiting:: Lower-level subroutines that they use.

Information about Files

* Testing Accessibility::   Is a given file readable?  Writable?
* Kinds of Files::          Is it a directory?  A link?
* File Attributes::         How large is it?  Any other names?  Etc.

File Names

* File Name Components::    The directory part of a file name, and the rest.
* Directory Names::         A directory's name as a directory
                              is different from its name as a file.
* Relative File Names::     Some file names are relative to a
                              current directory.
* File Name Expansion::     Converting relative file names to absolute ones.
* Unique File Names::       Generating names for temporary files.
* File Name Completion::    Finding the completions for a given file name.

Backups and Auto-Saving

* Backup Files::            How backup files are made; how their names
                              are chosen.
* Auto-Saving::             How auto-save files are made; how their
                              names are chosen.
* Reverting::               `revert-buffer', and how to customize
                              what it does.

Backup Files

* Making Backups::          How XEmacs makes backup files, and when.
* Rename or Copy::          Two alternatives: renaming the old file
                              or copying it.
* Numbered Backups::        Keeping multiple backups for each source file.
* Backup Names::            How backup file names are computed; customization.

Buffers

* Buffer Basics::           What is a buffer?
* Buffer Names::            Accessing and changing buffer names.
* Buffer File Name::        The buffer file name indicates which file
                              is visited.
* Buffer Modification::     A buffer is "modified" if it needs to be saved.
* Modification Time::       Determining whether the visited file was changed
                              ``behind XEmacs's back''.
* Read Only Buffers::       Modifying text is not allowed in a
                              read-only buffer.
* The Buffer List::         How to look at all the existing buffers.
* Creating Buffers::        Functions that create buffers.
* Killing Buffers::         Buffers exist until explicitly killed.
* Current Buffer::          Designating a buffer as current
                              so primitives will access its contents.

Windows

* Basic Windows::           Basic information on using windows.
* Splitting Windows::       Splitting one window into two windows.
* Deleting Windows::        Deleting a window gives its space to other windows.
* Selecting Windows::       The selected window is the one that you edit in.
* Cyclic Window Ordering::  Moving around the existing windows.
* Buffers and Windows::     Each window displays the contents of a buffer.
* Displaying Buffers::      Higher-lever functions for displaying a buffer
                              and choosing a window for it.
* Window Point::            Each window has its own location of point.
* Window Start::            The display-start position controls which text
                              is on-screen in the window.
* Vertical Scrolling::      Moving text up and down in the window.
* Horizontal Scrolling::    Moving text sideways on the window.
* Size of Window::          Accessing the size of a window.
* Resizing Windows::        Changing the size of a window.
* Window Configurations::   Saving and restoring the state of the screen.

Frames

* Creating Frames::	    Creating additional frames.
* Frame Properties::	    Controlling frame size, position, font, etc.
* Frame Titles::            Automatic updating of frame titles.
* Deleting Frames::	    Frames last until explicitly deleted.
* Finding All Frames::	    How to examine all existing frames.
* Frames and Windows::	    A frame contains windows;
			      display of text always works through windows.
* Minibuffers and Frames::  How a frame finds the minibuffer to use.
* Input Focus::		    Specifying the selected frame.
* Visibility of Frames::    Frames may be visible or invisible, or icons.
* Raising and Lowering::    Raising a frame makes it hide other X windows;
			      lowering it makes the others hide them.
* Frame Hooks::             Hooks for customizing frame behavior.

Positions

* Point::                   The special position where editing takes place.
* Motion::                  Changing point.
* Excursions::              Temporary motion and buffer changes.
* Narrowing::               Restricting editing to a portion of the buffer.

Motion

* Character Motion::        Moving in terms of characters.
* Word Motion::             Moving in terms of words.
* Buffer End Motion::       Moving to the beginning or end of the buffer.
* Text Lines::              Moving in terms of lines of text.
* Screen Lines::            Moving in terms of lines as displayed.
* List Motion::             Moving by parsing lists and sexps.
* Skipping Characters::     Skipping characters belonging to a certain set.

Markers

* Overview of Markers::     The components of a marker, and how it relocates.
* Predicates on Markers::   Testing whether an object is a marker.
* Creating Markers::        Making empty markers or markers at certain places.
* Information from Markers::  Finding the marker's buffer or character
                                position.
* Changing Markers::        Moving the marker to a new buffer or position.
* The Mark::                How ``the mark'' is implemented with a marker.
* The Region::              How to access ``the region''.

Text

* Near Point::       Examining text in the vicinity of point.
* Buffer Contents::  Examining text in a general fashion.
* Comparing Text::   Comparing substrings of buffers.
* Insertion::        Adding new text to a buffer.
* Commands for Insertion::  User-level commands to insert text.
* Deletion::         Removing text from a buffer.
* User-Level Deletion::     User-level commands to delete text.
* The Kill Ring::    Where removed text sometimes is saved for later use.
* Undo::             Undoing changes to the text of a buffer.
* Maintaining Undo:: How to enable and disable undo information.
			How to control how much information is kept.
* Filling::          Functions for explicit filling.
* Margins::          How to specify margins for filling commands.
* Auto Filling::     How auto-fill mode is implemented to break lines.
* Sorting::          Functions for sorting parts of the buffer.
* Columns::          Computing horizontal positions, and using them.
* Indentation::      Functions to insert or adjust indentation.
* Case Changes::     Case conversion of parts of the buffer.
* Text Properties::  Assigning Lisp property lists to text characters.
* Substitution::     Replacing a given character wherever it appears.
* Registers::        How registers are implemented.  Accessing the text or
                       position stored in a register.
* Transposition::    Swapping two portions of a buffer.
* Change Hooks::     Supplying functions to be run when text is changed.

The Kill Ring

* Kill Ring Concepts::      What text looks like in the kill ring.
* Kill Functions::          Functions that kill text.
* Yank Commands::           Commands that access the kill ring.
* Low-Level Kill Ring::	    Functions and variables for kill ring access.
* Internals of Kill Ring::  Variables that hold kill-ring data.

Indentation

* Primitive Indent::        Functions used to count and insert indentation.
* Mode-Specific Indent::    Customize indentation for different modes.
* Region Indent::           Indent all the lines in a region.
* Relative Indent::         Indent the current line based on previous lines.
* Indent Tabs::             Adjustable, typewriter-like tab stops.
* Motion by Indent::        Move to first non-blank character.

Searching and Matching

* String Search::           Search for an exact match.
* Regular Expressions::     Describing classes of strings.
* Regexp Search::           Searching for a match for a regexp.
* Match Data::              Finding out which part of the text matched
                              various parts of a regexp, after regexp search.
* Saving Match Data::       Saving and restoring this information.
* Standard Regexps::        Useful regexps for finding sentences, pages,...
* Searching and Case::      Case-independent or case-significant searching.

Regular Expressions

* Syntax of Regexps::       Rules for writing regular expressions.
* Regexp Example::          Illustrates regular expression syntax.

Syntax Tables

* Syntax Descriptors::      How characters are classified.
* Syntax Table Functions::  How to create, examine and alter syntax tables.
* Parsing Expressions::     Parsing balanced expressions
                              using the syntax table.
* Standard Syntax Tables::  Syntax tables used by various major modes.
* Syntax Table Internals::  How syntax table information is stored.

Syntax Descriptors

* Syntax Class Table::      Table of syntax classes.
* Syntax Flags::            Additional flags each character can have.

Abbrevs And Abbrev Expansion

* Abbrev Mode::             Setting up XEmacs for abbreviation.
* Tables: Abbrev Tables.    Creating and working with abbrev tables.
* Defining Abbrevs::        Specifying abbreviations and their expansions.
* Files: Abbrev Files.      Saving abbrevs in files.
* Expansion: Abbrev Expansion.  Controlling expansion; expansion subroutines.
* Standard Abbrev Tables::  Abbrev tables used by various major modes.

Extents

* Intro to Extents::	   Extents are regions over a buffer or string.
* Creating and Modifying Extents::
			   Basic extent functions.
* Extent Endpoints::	   Accessing and setting the bounds of an extent.
* Finding Extents::	   Determining which extents are in an object.
* Mapping Over Extents::   More sophisticated functions for extent scanning.
* Extent Properties::	   Extents have built-in and user-definable properties.
* Detached Extents::	   Extents that are not in a buffer.
* Extent Parents::         Inheriting properties from another extent.
* Duplicable Extents::	   Extents can be marked to be copied into strings.
* Extents and Events::	   Extents can interact with the keyboard and mouse.
* Atomic Extents::	   Treating a block of text as a single entity.

Specifiers

* Introduction to Specifiers::	Specifiers provide a clean way for
				display and other properties to vary
				(under user control) in a wide variety
				of contexts.
* Specifiers In-Depth::		Gory details about specifier innards.
* Specifier Instancing::	Instancing means obtaining the ``value'' of
				a specifier in a particular context.
* Specifier Types::		Specifiers come in different flavors.
* Adding Specifications::	Specifications control a specifier's ``value''
				by giving conditions under which a
				particular value is valid.
* Retrieving Specifications::	Querying a specifier's specifications.
* Specifier Instancing Functions::
				Functions to instance a specifier.
* Specifier Examples::		Making all this stuff clearer.
* Creating Specifiers::		Creating specifiers for your own use.
* Specifier Validation Functions::
				Validating the components of a specifier.
* Other Specification Functions::
				Other ways of working with specifications.

Faces and Window-System Objects

* Faces::		Controlling the way text looks.
* Fonts::		Controlling the typeface of text.
* Colors::		Controlling the color of text and pixmaps.

Faces

* Merging Faces::		How XEmacs decides which face to use
				  for a character.
* Basic Face Functions::	How to define and examine faces.
* Face Properties::		How to access and modify a face's properties.
* Face Convenience Functions::	Convenience functions for accessing
				  particular properties of a face.
* Other Face Display Functions:: Other functions pertaining to how a
				  a face appears.

Fonts

* Font Specifiers::		Specifying how a font will appear.
* Font Instances::		What a font specifier gets instanced as.
* Font Instance Names::		The name of a font instance.
* Font Instance Size::		The size of a font instance.
* Font Instance Characteristics:: Display characteristics of font instances.
* Font Convenience Functions::	Convenience functions that automatically
				  instance and retrieve the properties
				  of a font specifier.

Colors

* Color Specifiers::		Specifying how a color will appear.
* Color Instances::		What a color specifier gets instanced as.
* Color Instance Properties::	Properties of color instances.
* Color Convenience Functions::	Convenience functions that automatically
				  instance and retrieve the properties
				  of a color specifier.

Glyphs

* Glyph Intro::		Glyphs are abstract image specifications.
* Images::		Specifying the appearance of glyphs.
* Using Glyphs::	Creating and displaying glyphs.
* Manipulating Glyphs::	Getting and setting glyph properties.
* Glyph Examples::	Examples of how to work with glyphs.

Images

* Image Specifiers::			Specifying an image's appearance.
* Image Instantiator Conversion::	Lazy realization of graphics.
* Image Instantiator Formats::		A catalog of image descriptors.
* Image Instances::			Classes of graphical objects.

Image Instances

* Image Instance Types::         Each image instances has a particular type.
* Image Instance Functions::	 Functions for working with image instances.

Using Glyphs


Image Instances

* Image Instance Types::         Each image instances has a particular type.
* Image Instance Functions::	 Functions for working with image instances.

Using Glyphs

* Creating Glyphs::	Creating new glyphs.
* Buffer Glyphs::	Annotations are glyphs that appear in a buffer.
* Redisplay Glyphs::	Glyphs controlling various redisplay functions.
* Frame Glyphs::	Displaying glyphs in GUI components of the frame.
* External Glyphs::	Icons and mouse pointers for the window system.
* Native GUI Widgets::	Complex active elements treated as a single glyph.
* Subwindows::		Externally-controlled subwindows in buffers.

Native GUI Widgets

* Introduction to Widgets::     Native widgets provide tight integration of
                                GUI features with the platform GUI.
* Lisp API to Native Widgets::  Native widgets are glyphs.
* Layouts::                     Specifying composite widgets from Lisp.
* Primitive Widgets::           Catalogue of available native widgets.

Manipulating Glyphs

* Glyph Properties::	Accessing and modifying a glyph's properties.
* Glyph Convenience Functions::  Accessing particular properties of a glyph.
* Glyph Dimensions::	Determining the height, width, etc. of a glyph.
* Glyph Types::		Each glyph has a particular type.

Annotations

* Annotation Basics::		Introduction to annotations.
* Annotation Primitives::	Creating and deleting annotations.
* Annotation Properties::	Retrieving and changing the characteristics
				  of an annotation.
* Margin Primitives::		Controlling the size of the margins.
* Locating Annotations::	Looking for annotations in a buffer.
* Annotation Hooks::		Hooks called at certain times during an
				  annotation's lifetime.

Hash Tables

* Introduction to Hash Tables::	Hash tables are fast data structures for
                                implementing simple tables (i.e. finite
                                mappings from keys to values).
* Working With Hash Tables::    Hash table functions.
* Weak Hash Tables::            Hash tables with special garbage-collection
                                behavior.

Range Tables

* Introduction to Range Tables:: Range tables efficiently map ranges of
                                 integers to values.
* Working With Range Tables::    Range table functions.


XEmacs Display

* Refresh Screen::      Clearing the screen and redrawing everything on it.
* Truncation::          Folding or wrapping long text lines.
* The Echo Area::       Where messages are displayed.
* Selective Display::   Hiding part of the buffer text.
* Overlay Arrow::       Display of an arrow to indicate position.
* Temporary Displays::  Displays that go away automatically.
* Blinking::            How XEmacs shows the matching open parenthesis.
* Usual Display::	The usual conventions for displaying nonprinting chars.
* Display Tables::	How to specify other conventions.
* Beeping::             Audible signal to the user.

Processes

* Subprocess Creation::     Functions that start subprocesses.
* Synchronous Processes::   Details of using synchronous subprocesses.
* Asynchronous Processes::  Starting up an asynchronous subprocess.
* Deleting Processes::      Eliminating an asynchronous subprocess.
* Process Information::     Accessing run-status and other attributes.
* Input to Processes::      Sending input to an asynchronous subprocess.
* Signals to Processes::    Stopping, continuing or interrupting
                              an asynchronous subprocess.
* Output from Processes::   Collecting output from an asynchronous subprocess.
* Sentinels::               Sentinels run when process run-status changes.
* Network::                 Opening network connections.

Receiving Output from Processes

* Process Buffers::         If no filter, output is put in a buffer.
* Filter Functions::        Filter functions accept output from the process.
* Accepting Output::        How to wait until process output arrives.

Operating System Interface

* Starting Up::             Customizing XEmacs start-up processing.
* Getting Out::             How exiting works (permanent or temporary).
* System Environment::      Distinguish the name and kind of system.
* Terminal Input::          Recording terminal input for debugging.
* Terminal Output::         Recording terminal output for debugging.
* Flow Control::            How to turn output flow control on or off.
* Batch Mode::              Running XEmacs without terminal interaction.

Starting Up XEmacs

* Start-up Summary::        Sequence of actions XEmacs performs at start-up.
* Init File::               Details on reading the init file (`.emacs').
* Terminal-Specific::       How the terminal-specific Lisp file is read.
* Command Line Arguments::  How command line arguments are processed,
                              and how you can customize them.

Getting out of XEmacs

* Killing XEmacs::           Exiting XEmacs irreversibly.
* Suspending XEmacs::        Exiting XEmacs reversibly.

X-Windows

* X Selections::		Transferring text to and from other X clients.
* X Server::			Information about the X server connected to
				  a particular device.
* Resources::			Getting resource values from the server.
* Server Data::			Getting info about the X server.
* Grabs::			Restricting access to the server by other apps.
* X Miscellaneous::             Other X-specific functions and variables.

ToolTalk Support

* XEmacs ToolTalk API Summary::
* Sending Messages::
* Receiving Messages::

LDAP Support

* Building XEmacs with LDAP support::  How to add LDAP support to XEmacs
* XEmacs LDAP API::             Lisp access to LDAP functions
* Syntax of Search Filters::    A brief summary of RFC 1558

XEmacs LDAP API

* LDAP Variables::              Lisp variables related to LDAP
* The High-Level LDAP API::     High-level LDAP lisp functions
* The Low-Level LDAP API::      Low-level LDAP lisp primitives
* LDAP Internationalization::   I18n variables and functions

The Low-Level LDAP API

* The LDAP Lisp Object::
* Opening and Closing a LDAP Connection::
* Low-level Operations on a LDAP Server::

LDAP Internationalization

* LDAP Internationalization Variables::
* Encoder/Decoder Functions::

Internationalization

* I18N Levels 1 and 2:: Support for different time, date, and currency formats.
* I18N Level 3::        Support for localized messages.
* I18N Level 4::        Support for Asian languages.

MULE

* Internationalization Terminology::
                        Definition of various internationalization terms.
* Charsets::            Sets of related characters.
* MULE Characters::     Working with characters in XEmacs/MULE.
* Composite Characters:: Making new characters by overstriking other ones.
* ISO 2022::            An international standard for charsets and encodings.
* Coding Systems::      Ways of representing a string of chars using integers.
* CCL::                 A special language for writing fast converters.
* Category Tables::     Subdividing charsets into groups.

Tips

* Style Tips::                Writing clean and robust programs.
* Compilation Tips::          Making compiled code run fast.
* Documentation Tips::        Writing readable documentation strings.
* Comment Tips::	      Conventions for writing comments.
* Library Headers::           Standard headers for library packages.

Building XEmacs and Object Allocation

* Building XEmacs::         How to preload Lisp libraries into XEmacs.
* Pure Storage::            A kludge to make preloaded Lisp functions sharable.
* Garbage Collection::      Reclaiming space for Lisp objects no longer used.


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.


File: lispref.info,  Node: Introduction,  Next: Packaging,  Prev: Copying,  Up: Top

1 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.


File: lispref.info,  Node: Caveats,  Next: Lisp History,  Up: Introduction

1.1 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


File: lispref.info,  Node: Lisp History,  Next: Conventions,  Prev: Caveats,  Up: Introduction

1.2 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.


File: lispref.info,  Node: Conventions,  Next: Acknowledgements,  Prev: Lisp History,  Up: Introduction

1.3 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.


File: lispref.info,  Node: Some Terms,  Next: nil and t,  Up: Conventions

1.3.1 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.


File: lispref.info,  Node: nil and t,  Next: Evaluation Notation,  Prev: Some Terms,  Up: Conventions

1.3.2 `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::.


File: lispref.info,  Node: Evaluation Notation,  Next: Printing Notation,  Prev: nil and t,  Up: Conventions

1.3.3 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)


File: lispref.info,  Node: Printing Notation,  Next: Error Messages,  Prev: Evaluation Notation,  Up: Conventions

1.3.4 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


File: lispref.info,  Node: Error Messages,  Next: Buffer Text Notation,  Prev: Printing Notation,  Up: Conventions

1.3.5 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


File: lispref.info,  Node: Buffer Text Notation,  Next: Format of Descriptions,  Prev: Error Messages,  Up: Conventions

1.3.6 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 ----------


File: lispref.info,  Node: Format of Descriptions,  Prev: Buffer Text Notation,  Up: Conventions

1.3.7 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'.


File: lispref.info,  Node: A Sample Function Description,  Next: A Sample Variable Description,  Up: Format of Descriptions

1.3.7.1 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.


File: lispref.info,  Node: A Sample Variable Description,  Prev: A Sample Function Description,  Up: Format of Descriptions

1.3.7.2 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'.


File: lispref.info,  Node: Acknowledgements,  Prev: Conventions,  Up: Introduction

1.4 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.


File: lispref.info,  Node: Packaging,  Next: Lisp Data Types,  Prev: Introduction,  Up: Top

2 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::


File: lispref.info,  Node: Package Overview,  Next: Package Terminology,  Up: Packaging

3 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::


File: lispref.info,  Node: The User View,  Next: The Library Maintainer View,  Up: Package Overview

3.1 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.


File: lispref.info,  Node: The Library Maintainer View,  Next: The Package Release Engineer View,  Prev: The User View,  Up: Package Overview

3.2 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.


File: lispref.info,  Node: Infrastructure,  Next: Control Files,  Up: The Library Maintainer View

3.2.1 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::.


File: lispref.info,  Node: Control Files,  Next: Obtaining,  Prev: Infrastructure,  Up: The Library Maintainer View

3.2.2 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.


File: lispref.info,  Node: Obtaining,  Prev: Control Files,  Up: The Library Maintainer View

3.2.3 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.


File: lispref.info,  Node: The Package Release Engineer View,  Prev: The Library Maintainer View,  Up: Package Overview

3.2.4 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.


File: lispref.info,  Node: Package Terminology,  Next: Building Packages,  Prev: Package Overview,  Up: Packaging

Package Terminology:
====================

3.2.5 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.

3.2.6 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.

3.2.7 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.


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.

3.2.8 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.

3.3 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.


File: lispref.info,  Node: Makefile Targets,  Next: Local.rules File,  Prev: Building Packages,  Up: Packaging

4 `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.

4.0.1 The targets that most people would be interested in would be:
-------------------------------------------------------------------

   * `all'

   * `bindist'

   * `html'

   * `install'

   * `install-only'

   * `clean'

   * `distclean'


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'


File: lispref.info,  Node: Creating Packages,  Next: Documenting Packages,  Prev: Local.rules File,  Up: Packaging

5 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'


File: lispref.info,  Node: package-info.in,  Next: Makefile,  Up: Creating Packages

6 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.


File: lispref.info,  Node: Makefile,  Prev: package-info.in,  Up: Creating Packages

7 `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.

7.1 `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.


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.


File: lispref.info,  Node: Issues,  Prev: Documenting Packages,  Up: Packaging

7.2 Issues
==========

To be completed.


File: lispref.info,  Node: Lisp Data Types,  Next: Numbers,  Prev: Packaging,  Up: Top

8 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.


File: lispref.info,  Node: Printed Representation,  Next: Comments,  Up: Lisp Data Types

8.1 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.


File: lispref.info,  Node: Comments,  Next: Primitive Types,  Prev: Printed Representation,  Up: Lisp Data Types

8.2 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.


File: lispref.info,  Node: Primitive Types,  Next: Programming Types,  Prev: Comments,  Up: Lisp Data Types

8.3 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


File: lispref.info,  Node: Programming Types,  Next: Editing Types,  Prev: Primitive Types,  Up: Lisp Data Types

8.4 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.


File: lispref.info,  Node: Integer Type,  Next: Floating Point Type,  Up: Programming Types

8.4.1 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.


File: lispref.info,  Node: Floating Point Type,  Next: Character Type,  Prev: Integer Type,  Up: Programming Types

8.4.2 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.


File: lispref.info,  Node: Character Type,  Next: Symbol Type,  Prev: Floating Point Type,  Up: Programming Types

8.4.3 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, there are two read syntaxes involving character codes.  It
is not possible to represent multibyte or wide characters in this way;
the permissible range of codes is from 0 to 255 (_i.e._, `0377' octal
or `0xFF' hexadecimal).  If you wish to convert code points to other
characters, you must use the `make-char' or `unicode-to-char'
primitives in Mule.  (Non-Mule XEmacsen cannot represent codes out of
that range at all, although you can set the font to a registry other
than ISO 8859/1 to get the appearance of a greater range of
characters.)  Although these syntaxes can represent any ASCII or
Latin-1 character, they are preferred only when the precise integral
value is more important than the ASCII representation.

   The first 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'.

   The second consists of a question mark followed by a backslash, the
character `x', and the character code in hexadecimal (up to two
hexadecimal digits); thus, `?\x41' for the character `A', `?\x1' for
the character `C-a', and `?\x2' for the character `C-b'.

   In both cases, the reader will finalize the character when a
non-digit is encountered or the maximum length of a character code is
reached.  It then starts reading the next token.

     ;; Under XEmacs 20:
     ?\012 => ?\n        ?\n => ?\n        ?\C-j => ?\n
     ?\101 => ?A         ?A => ?A          ?\x0A => ?\n
     ?\x41 => ?A     '(?\xAZ) => '(?\n Z)  '(?\0123) => (?\n 3)
     ;; Under XEmacs 19:
     ?\012 => 10         ?\n => 10         ?\C-j => 10
     ?\101 => 65         ?A => 65
     ;; ?\x41 is a syntax error.

   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.


File: lispref.info,  Node: Symbol Type,  Next: Sequence Type,  Prev: Character Type,  Up: Programming Types

8.4.4 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.


File: lispref.info,  Node: Sequence Type,  Next: Cons Cell Type,  Prev: Symbol Type,  Up: Programming Types

8.4.5 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'.


File: lispref.info,  Node: Cons Cell Type,  Next: Array Type,  Prev: Sequence Type,  Up: Programming Types

8.4.6 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.


File: lispref.info,  Node: Dotted Pair Notation,  Next: Association List Type,  Up: Cons Cell Type

8.4.6.1 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


File: lispref.info,  Node: Association List Type,  Prev: Dotted Pair Notation,  Up: Cons Cell Type

8.4.6.2 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.


File: lispref.info,  Node: Array Type,  Next: String Type,  Prev: Cons Cell Type,  Up: Programming Types

8.4.7 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.


File: lispref.info,  Node: String Type,  Next: Vector Type,  Prev: Array Type,  Up: Programming Types

8.4.8 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.


File: lispref.info,  Node: Vector Type,  Next: Bit Vector Type,  Prev: String Type,  Up: Programming Types

8.4.9 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.


File: lispref.info,  Node: Bit Vector Type,  Next: Function Type,  Prev: Vector Type,  Up: Programming Types

8.4.10 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.


File: lispref.info,  Node: Function Type,  Next: Macro Type,  Prev: Bit Vector Type,  Up: Programming Types

8.4.11 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::.


File: lispref.info,  Node: Macro Type,  Next: Primitive Function Type,  Prev: Function Type,  Up: Programming Types

8.4.12 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.


File: lispref.info,  Node: Primitive Function Type,  Next: Compiled-Function Type,  Prev: Macro Type,  Up: Programming Types

8.4.13 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.


File: lispref.info,  Node: Compiled-Function Type,  Next: Autoload Type,  Prev: Primitive Function Type,  Up: Programming Types

8.4.14 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
`#[...]'.


File: lispref.info,  Node: Autoload Type,  Next: Char Table Type,  Prev: Compiled-Function Type,  Up: Programming Types

8.4.15 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.


File: lispref.info,  Node: Char Table Type,  Next: Hash Table Type,  Prev: Autoload Type,  Up: Programming Types

8.4.16 Char Table Type
----------------------

(not yet documented)


File: lispref.info,  Node: Hash Table Type,  Next: Range Table Type,  Prev: Char Table Type,  Up: Programming Types

8.4.17 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.


File: lispref.info,  Node: Range Table Type,  Next: Weak List Type,  Prev: Hash Table Type,  Up: Programming Types

8.4.18 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.


File: lispref.info,  Node: Weak List Type,  Prev: Range Table Type,  Up: Programming Types

8.4.19 Weak List Type
---------------------

(not yet documented)


File: lispref.info,  Node: Editing Types,  Next: Window-System Types,  Prev: Programming Types,  Up: Lisp Data Types

8.5 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.


File: lispref.info,  Node: Buffer Type,  Next: Marker Type,  Up: Editing Types

8.5.1 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">


File: lispref.info,  Node: Marker Type,  Next: Extent Type,  Prev: Buffer Type,  Up: Editing Types

8.5.2 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.


File: lispref.info,  Node: Extent Type,  Next: Window Type,  Prev: Marker Type,  Up: Editing Types

8.5.3 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::.


File: lispref.info,  Node: Window Type,  Next: Frame Type,  Prev: Extent Type,  Up: Editing Types

8.5.4 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.


File: lispref.info,  Node: Frame Type,  Next: Device Type,  Prev: Window Type,  Up: Editing Types

8.5.5 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.


File: lispref.info,  Node: Device Type,  Next: Console Type,  Prev: Frame Type,  Up: Editing Types

8.5.6 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.


File: lispref.info,  Node: Console Type,  Next: Window Configuration Type,  Prev: Device Type,  Up: Editing Types

8.5.7 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.


File: lispref.info,  Node: Window Configuration Type,  Next: Event Type,  Prev: Console Type,  Up: Editing Types

8.5.8 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.


File: lispref.info,  Node: Event Type,  Next: Process Type,  Prev: Window Configuration Type,  Up: Editing Types

8.5.9 Event Type
----------------

(not yet documented)


File: lispref.info,  Node: Process Type,  Next: Stream Type,  Prev: Event Type,  Up: Editing Types

8.5.10 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.


File: lispref.info,  Node: Stream Type,  Next: Keymap Type,  Prev: Process Type,  Up: Editing Types

8.5.11 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.


File: lispref.info,  Node: Keymap Type,  Next: Syntax Table Type,  Prev: Stream Type,  Up: Editing Types

8.5.12 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.


File: lispref.info,  Node: Syntax Table Type,  Next: Display Table Type,  Prev: Keymap Type,  Up: Editing Types

8.5.13 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.


File: lispref.info,  Node: Display Table Type,  Next: Database Type,  Prev: Syntax Table Type,  Up: Editing Types

8.5.14 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::.


File: lispref.info,  Node: Database Type,  Next: Charset Type,  Prev: Display Table Type,  Up: Editing Types

8.5.15 Database Type
--------------------

(not yet documented)


File: lispref.info,  Node: Charset Type,  Next: Coding System Type,  Prev: Database Type,  Up: Editing Types

8.5.16 Charset Type
-------------------

(not yet documented)


File: lispref.info,  Node: Coding System Type,  Next: ToolTalk Message Type,  Prev: Charset Type,  Up: Editing Types

8.5.17 Coding System Type
-------------------------

(not yet documented)


File: lispref.info,  Node: ToolTalk Message Type,  Next: ToolTalk Pattern Type,  Prev: Coding System Type,  Up: Editing Types

8.5.18 ToolTalk Message Type
----------------------------

(not yet documented)


File: lispref.info,  Node: ToolTalk Pattern Type,  Prev: ToolTalk Message Type,  Up: Editing Types

8.5.19 ToolTalk Pattern Type
----------------------------

(not yet documented)


File: lispref.info,  Node: Window-System Types,  Next: Type Predicates,  Prev: Editing Types,  Up: Lisp Data Types

8.6 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.


File: lispref.info,  Node: Face Type,  Next: Glyph Type,  Up: Window-System Types

8.6.1 Face Type
---------------

(not yet documented)


File: lispref.info,  Node: Glyph Type,  Next: Specifier Type,  Prev: Face Type,  Up: Window-System Types

8.6.2 Glyph Type
----------------

(not yet documented)


File: lispref.info,  Node: Specifier Type,  Next: Font Instance Type,  Prev: Glyph Type,  Up: Window-System Types

8.6.3 Specifier Type
--------------------

(not yet documented)


File: lispref.info,  Node: Font Instance Type,  Next: Color Instance Type,  Prev: Specifier Type,  Up: Window-System Types

8.6.4 Font Instance Type
------------------------

(not yet documented)


File: lispref.info,  Node: Color Instance Type,  Next: Image Instance Type,  Prev: Font Instance Type,  Up: Window-System Types

8.6.5 Color Instance Type
-------------------------

(not yet documented)


File: lispref.info,  Node: Image Instance Type,  Next: Toolbar Button Type,  Prev: Color Instance Type,  Up: Window-System Types

8.6.6 Image Instance Type
-------------------------

(not yet documented)


File: lispref.info,  Node: Toolbar Button Type,  Next: Subwindow Type,  Prev: Image Instance Type,  Up: Window-System Types

8.6.7 Toolbar Button Type
-------------------------

(not yet documented)


File: lispref.info,  Node: Subwindow Type,  Next: X Resource Type,  Prev: Toolbar Button Type,  Up: Window-System Types

8.6.8 Subwindow Type
--------------------

(not yet documented)


File: lispref.info,  Node: X Resource Type,  Prev: Subwindow Type,  Up: Window-System Types

8.6.9 X Resource Type
---------------------

(not yet documented)


File: lispref.info,  Node: Type Predicates,  Next: Equality Predicates,  Prev: Window-System Types,  Up: Lisp Data Types

8.7 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


File: lispref.info,  Node: Equality Predicates,  Prev: Type Predicates,  Up: Lisp Data Types

8.8 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).


File: lispref.info,  Node: Numbers,  Next: Strings and Characters,  Prev: Lisp Data Types,  Up: Top

9 Numbers
*********

XEmacs supports two to five numeric data types.  "Integers" and
"floating point numbers" are always supported.  As a build-time option,
"bignums", "ratios", and "bigfloats" may be enabled on some platforms.

   Integers, which are what Common Lisp calls "fixnums", are whole
numbers such as -3, 0, #b0111, #xFEED, #o744.  Their values are exact,
and their range is limited.  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.

   Bignums are arbitrary precision integers.  When supported, XEmacs can
handle any integral calculations you have enough virtual memory to
store.  (More precisely, on current architectures the representation
allows integers whose storage would exhaust the address space.)  They
are notated in the same way as other integers (fixnums).  XEmacs
automatically converts results of computations from fixnum to bignum,
and back, depending on the storage required to represent the number.
Thus use of bignums are entirely transparent to the user, except for a
few special applications that expect overflows.  Ratios are rational
numbers with arbitrary precision.  They are notated in the usual way
with the solidus, for example 5/3 or -22/7.

   Bigfloats are floating point numbers with arbitrary precision, which
may be specified by the user (and may be different for different
bigfloats at the same time).  Unlike integers, which are always
infinitely precise if they can be represented, floating point numbers
are inherently imprecise.  This means that choice of precision can be a
very delicate issue.  XEmacs automatically converts _from float to
bigfloat_ when floats and bigfloats are mixed in an expression, but a
bigfloat will never be converted to a float unless the user explicitly
coerces the value.  Nor will the result of a float operation be
converted to bigfloat, except for "contagion" from another operand that
is already a bigfloat.  However, when bigfloats of differing precision
are mixed, the result will always have the larger precision.  The exact
rules are more carefully explained elsewhere (*note Canonicalization
and Contagion::).

   Note that the term "integer" is used throughout the XEmacs
documentation and code to mean "fixnum".  This is inconsistent with
Common Lisp, and likely to cause confusion.  Similarly, "float" is used
to mean "fixed precision floating point number", and the Common Lisp
distinctions among "short-floats", "long-floats", _etc._, and bigfloats
(which are not standardized in Common Lisp) are not reflected in XEmacs
terminology.  (Volunteers to fix this in the XEmacs manuals would be
heartily welcomed.)

* Menu:

* Integer Basics::            Representation and range of integers.
* Rational Basics::           Representation and range of rational numbers.
* Float Basics::              Representation and range of floating point.
* The Bignum Extension::      Arbitrary precision integers, ratios, and floats.
* 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.


File: lispref.info,  Node: Integer Basics,  Next: Rational Basics,  Up: Numbers

9.1 Integer Basics
==================

The range of values for an integer depends on the machine.    If a
multiple-precision arithmetic library is available on your platform,
support for bignums, that is, integers with arbitrary precision, may be
compiled in to your XEmacs.  The rest of this section assumes that the
bignum extension is _not_ available.  The bignum extension and the
user-visible differences in normal integer arithmetic are discussed in a
separate section *Note The Bignum Extension::.

   The minimum range is -1073741824 to 1073741823 (31 bits; i.e., -2**30
to 2**30 - 1), but some machines may provide a wider range.  Many
examples in this chapter assume an integer has 31 bits.  

   The range of fixnums is available to Lisp programs:

 -- Variable: most-positive-fixnum
     The fixed-precision integer closest in value to positive infinity.

 -- Variable: most-negative-fixnum
     The fixed-precision integer closest in value to negative infinity.

   Here is a common idiom to temporarily suppress garbage collection:
     (garbage-collect)
     (let ((gc-cons-threshold most-positive-fixnum))
       ;; allocation-intensive computation
       )
     (garbage-collect)

   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.
      2147483648      ; Read error, 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 31-bit binary, the decimal integer 5 looks like this:

     000 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:

     111 1111  1111 1111  1111 1111  1111 1111

-1 is represented as 31 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:

     111 1111  1111 1111  1111 1111  1111 1011

   In this implementation, the largest 31-bit binary integer is the
decimal integer 1,073,741,823.  In binary, it looks like this:

     011 1111  1111 1111  1111 1111  1111 1111

   Since the arithmetic functions do not check whether integers go
outside their range, when you add 1 to 1,073,741,823, the value is the
negative integer -1,073,741,824:

     (+ 1 1073741823)
          => -1073741824
          => 100 0000  0000 0000  0000 0000  0000 0000

   Many of the arithmetic 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.


File: lispref.info,  Node: Rational Basics,  Next: Float Basics,  Prev: Integer Basics,  Up: Numbers

9.2 Rational Basics
===================

Ratios (built-in rational numbers) are available only when the bignum
extension is built into your XEmacs.  This facility is new and
experimental.  It is discussed in a separate section for convenience of
updating the documentation *Note The Bignum Extension::.  The following
functions are defined regardless of the presence of the extension, but
have trivial results for integers.

 -- Function: numerator rational
     Return the numerator of the canonical form of RATIONAL.  If
     RATIONAL is an integer, RATIONAL is returned.  RATIONAL must be an
     integer or a ratio.

 -- Function: denominator rational
     Return the denominator of the canonical form of RATIONAL.  If
     RATIONAL is an integer, 1 is returned.  RATIONAL must be an
     integer or a ratio.


File: lispref.info,  Node: Float Basics,  Next: The Bignum Extension,  Prev: Rational Basics,  Up: Numbers

9.3 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.  If a multiple-precision
arithmetic library is available on your platform, support for
bigfloats, that is, floating point numbers with arbitrary precision,
may be compiled in to your XEmacs.  The rest of this section assumes
that the bignum extension is _not_ available.  The bigfloat extension
and the user-visible differences in normal float arithmetic are
discussed in a separate section *Note The Bignum Extension::.

   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.

   The range of floats is available to Lisp programs:

 -- Variable: most-positive-float
     The fixed-precision floating-point-number closest in value to
     positive infinity.

 -- Variable: most-negative-float
     The fixed-precision floating point number closest in value to
     negative infinity.

 -- Variable: least-positive-float
     The positive float closest in value to 0.  May not be normalized.

 -- Variable: least-negative-float
     The positive float closest in value to 0.  Must be normalized.

 -- Variable: least-positive-normalized-float
     The negative float closest in value to 0.  May not be normalized.

 -- Variable: least-negative-normalized-float
     The negative float closest in value to 0.  Must be normalized.

   Note that for floating point numbers there is an interesting limit on
how small they can get, as well as a limit on how big they can get.  In
some representations, a floating point number is "normalized" if the
leading digit is non-zero.  This allows representing numbers smaller
than the most-negative exponent can express, by having fractional
mantissas.  This means that the number is less precise than a normalized
floating point number, so Lisp programs can detect loss of precision due
to unnormalized floats by checking whether the number is between
`least-positive-float' and `least-positive-normalized-float'.


File: lispref.info,  Node: The Bignum Extension,  Next: Predicates on Numbers,  Prev: Float Basics,  Up: Numbers

9.4 The Bignum Extension
========================

In XEmacs 21.5.18, an extension was added by Jerry James
<james@xemacs.org> to allow linking with arbitrary-precision arithmetic
libraries if they are available on your platform.  "Arbitrary"
precision means precisely what it says.  Your ability to work with large
numbers is limited only by the amount of virtual memory (and time) you
can throw at them.

   As of 09 April 2004, support for the GNU Multiple Precision
arithmetic library (GMP) is nearly complete, and support for the BSD
Multiple Precision arithmetic library (MP) is being debugged.  To enable
bignum support using GMP (respectively MP), invoke configure with your
usual options, and add `--use-number-lib=gmp' (respectively
`--use-number-lib=mp').  The default is to disable bignum support, but
if you are using a script to automate the build process, it may be
convenient to explicitly disable support by _appending_
`--use-number-lib=no' to your invocation of configure.  GMP has an MP
compatibility mode, but it is not recommended, as there remain poorly
understood bugs (even more so than for other vendors' versions of MP).

   With GMP, exact arithmetic with integers and ratios of arbitrary
precision and approximate ("floating point") arithmetic of arbitrary
precision are implemented efficiently in the library.  (Note that
numerical implementations are quite delicate and sensitive to
optimization.  If the library was poorly optimized for your hardware, as
is often the case with Linux distributions for 80x86, you may achieve
gains of _several orders of magnitude_ by rebuilding the MP library.
See `http://www.swox.com/gmp/gmp-speed.html'.)  The MP implementation
provides arbitrary precision integers.  Ratios and arbitrary precision
floats are not available with MP.

   If your code needs to run correctly whether or not the feature is
provided, you may test for the features `bignum', `ratio', and
`bigfloat'.

   The XEmacs bignum facility implements the Common Lisp notions of
"canonicalization" and "contagion".  Canonicalization means that in
exact (integer and ratio) arithmetic, a result of an operation is
always converted to the "smallest" type that can represent it exactly.
For exact numbers, the user only cares if efficiency is extremely
important; Lisp does not try to determine an order of computation that
avoids conversion to bignum (or ratio) even if one is available.  (Note
that integers are never silently converted to ratios: the result of `(/
1 2)' is the integer `0'.  You can _request_ that a ratio be used if
needed with `(div 1 2)'.)

   Since floating point arithmetic is inherently imprecise, numbers are
implicitly coerced to bigfloats only if other operands in the expression
are bigfloat, and bigfloats are only coerced to other numerical types by
explicit calls to the function `coerce'.

   Bignum support is incomplete.  If you would like to help with bignum
support, especially on BSD MP, please subscribe to the XEmacs Beta
mailing list (http://www.xemacs.org/Lists/#xemacs-beta), and book up on
`number-gmp.h' and `number-mp.h'.  Jerry has promised to write
internals documentation eventually, but if your skills run more to
analysis and documentation than to writing new code, feel free to fill
in the gap!

* Menu:

* Bignum Basics::             Representation and range of integers.
* Ratio Basics::              Representation and range of rational numbers.
* Bigfloat Basics::           Representation and range of floating point.
* Canonicalization and Contagion::  Automatic coercion to other types.
* Compatibility Issues::      Changes in fixed-precision arithmetic.


File: lispref.info,  Node: Bignum Basics,  Next: Ratio Basics,  Up: The Bignum Extension

9.4.1 Bignum Basics
-------------------

In most cases, bignum support should be transparent to users and Lisp
programmers.  A bignum-enabled XEmacs will automatically convert from
fixnums to bignums and back in pure integer arithmetic, and for GNU MP,
from floats to bigfloats.  (Bigfloats must be explicitly coerced to
other types, even if they are exactly representable by less precise
types.)  The Lisp reader and printer have been enhanced to handle
bignums, as have the mathematical functions.  Rationals (fixnums,
bignums, and ratios) are printed using the `%d', `%o', `%x', and `%u'
format conversions.


File: lispref.info,  Node: Ratio Basics,  Next: Bigfloat Basics,  Prev: Bignum Basics,  Up: The Bignum Extension

9.4.2 Ratio Basics
------------------

Ratios, when available have the read syntax and print representation
`3/5'.  Like other rationals (fixnums and bignums), they are printed
using the `%d', `%o', `%x', and `%u' format conversions.


File: lispref.info,  Node: Bigfloat Basics,  Next: Canonicalization and Contagion,  Prev: Ratio Basics,  Up: The Bignum Extension

9.4.3 Bigfloat Basics
---------------------

Bigfloats, when available, have the same read syntax and print
representations as fixed-precision floats.

   It is possible to make bigfloat the default floating point format by
setting `default-float-precision' to a non-zero value.  Precision is
given in bits, with a maximum precision of `bigfloat-max-prec'.
Bigfloats are created automatically when a number with yes


File: lispref.info,  Node: Canonicalization and Contagion,  Next: Compatibility Issues,  Prev: Bigfloat Basics,  Up: The Bignum Extension

9.4.4 Canonicalization and Contagion
------------------------------------

"Canonicalization" is a rule intended to enhance the time and space
efficiency of exact arithmetic.  Because bignums and ratios are
implemented as record objects, they take up much more space than
fixnums, which are implemented as an immediate object.  Conversions and
calls to the MP library also take time.  So the implementation always
converts the result of exact arithmetic to the smallest representation
that can exactly represent the quantity.

     (+ 3/4 5)
         => 23/4

     (+ 3/4 1/4 2)
         => 3

   Conversely, if an integer (read or computed) cannot be represented
as a fixnum, a bignum will be used.  Integer division is a somewhat
exceptional case.  Because it is useful and is the historical meaning of
the function `/', a separate function `div' is provided.  `div' is
identical to `/' except that when the rational result is not an
integer, it is represented exactly as a ratio.  In both cases if a
rational result is an integer, it is automatically converted to the
appropriate integral representation.

   Note that the efficiency gain from canonicalization is likely to be
less than you might think. Experience with numerical analysis shows that
in very precise calculations, the required precision tends to increase.
Thus it is typically wasted effort to attempt to convert to smaller
representations, as the number is often reused and requires a larger
representation.  However, XEmacs Lisp presumes that calculations using
bignums are the exception, so it applies canonicalization.

   "Contagion" is one way to address the requirement that an arithmetic
operation should not fail because of differing types of the operands.
Contagion is the idea that less precise operands are converted to the
more precise type, and then the operation is performed.  While changing
precision is a delicate issue, contagion is so useful that XEmacs
performs it automatically.

   In XEmacs, the following rules of contagion are used:

  1. If an expression mixes an integral type with a ratio, then the
     usual rules of rational arithmetic apply.  (If the result of the
     expression happens to be an integer, it will be canonicalized to
     integer.)

  2. If an expression mixes a rational type (fixnum, bignum, or ratio)
     with a float, the rational operand is converted to a float and the
     operation performed if the result would fit in a float, otherwise
     both operands are promoted to bigfloat, and the operation
     performed.

  3. If an expression mixes any other type with a bigfloat, the other
     operand is converted to bigfloat and the operation performed.

  4. If bigfloats of different precision are mixed, all are converted
     to the _highest_ precision, and the operation performed.

   Note that there are no rules to canonicalize floats or bigfloats.
This might seem surprising, but in both cases information will be lost.
Any floating point representation is implicitly approximate.  A
conversion to a rational type, even if it seems exact, loses this
information.  More subtly, demoting a bigfloat to a smaller bigfloat or
to a float would lose information about the precision of the result,
and thus some information about the accuracy.  Thus floating point
numbers are always already in canonical form.

   Of course the programmer can explicitly request canonicalization, or
more coercion to another type.  Coercion uses the Common Lisp
compatibility function `coerce' from the `cl-extra.el' library.  A
number can be explicitly converted to canonical form according to the
above rules using

 -- Function: canonicalize-number number
     Return the canonical form of NUMBER.

   However, if we've done our job properly, this is always a no-op.
That is, if you find a number in un-canonicalized form, please report
it as a bug.


File: lispref.info,  Node: Compatibility Issues,  Prev: Canonicalization and Contagion,  Up: The Bignum Extension

9.4.5 Compatibility Issues
--------------------------

_Surgeon General's Warning_: The automatic conversions cannot be
disabled at runtime.  Old functions will not produce ratios unless there
is a ratio operand, so there should be few surprises with type
conflicts (the contagion rules are quite natural for Lisp programmers
used to the behavior of integers and floats in pre-21.5.18 XEmacsen),
but they can't be ruled out.  Also, if you work with extremely large
numbers, your machine may arbitrarily decide to hand you an unpleasant
surprise rather than a bignum.

   User-visible changes in behavior include (in probable order of
annoyance)

   * Arithmetic can cause a segfault, depending on your MP library.

     GMP by default allocates temporaries on the stack.  If you run out
     of stack space, you're dead; there is no way that we know of to
     reliably detect this condition, because `alloca' is typically
     implemented to be _fast_ rather than robust.  If you just need a
     little more oomph, use a bigger stack (_e.g._, the `ulimit -s'
     command in bash(1)).  If you want robustness at the cost of speed,
     configure GMP with `--disable-alloca' and rebuild the GMP library.

     We do not know whether BSD MP uses `alloca' or not.  Please send
     any information you have as a bug report (`M-x report-xemacs-bug
     <RET>'), which will give us platform information.  (We do know that
     BSD MP implementations vary across vendors, but how much, we do
     not know yet.)

   * Terminology is not Common-Lisp-conforming.  For example, "integer"
     for Emacs Lisp means what Common Lisp calls "fixnum".  This issue
     is being investigated, but the use of "integer" for fixnum is
     pervasive and may cause backward-compatibility and
     GNU-Emacs-compatibility problems.  There are similar issues for
     floating point numbers.  Since Emacs Lisp has not had a ratio type
     before, there should be no problems there.

   * An atom with ratio read syntax now returns a number, not a symbol.

   * Many operations that used to cause a range error now succeed, with
     intermediate results and return values coerced to bignums as
     needed.

   * The `%u' format conversion will now give an error if its argument
     is negative.  (Without MP, it prints a number which Lisp can't
     read.)

   This is not a compatibility issue in the sense of specification, but
careless programmers who have taken advantage of the immediate
representation for numbers and written `(eq x y)' are in for a
surprise.  This doesn't work with bignums, even if both arguments are
bignums!  Arbitrary precision obviously requires consing new objects
because the objects are "large" and of variable size, and the
definition of `eq' does not permit different objects to compare as
equal.  Instead of `eq', use `eql', in which numbers of the same type
which have equal values compare equal, or `=', which does any necessary
type coercions before comparing for equality *Note Comparison of
Numbers::.


File: lispref.info,  Node: Predicates on Numbers,  Next: Comparison of Numbers,  Prev: The Bignum Extension,  Up: Numbers

9.5 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 which test for
type can take any type of Lisp object as argument (the more general
predicates would not be of much use otherwise).  However, the `zerop'
predicate requires a number as its argument, and the `evenp', and
`oddp' predicates require integers as their arguments.  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: numberp object
     This predicate tests whether its argument is a number (either
     integer or floating point), and returns `t' if so, `nil' otherwise.

 -- Function: realp object
     The `realp' predicate tests to see whether OBJECT is a rational or
     floating point number, and returns `t' if so, `nil' otherwise.
     Currently equivalent to `numberp'.

 -- 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)'.

 -- Function: integerp object
     This predicate tests whether its argument is an integer, and
     returns `t' if so, `nil' otherwise.

 -- Function: oddp integer
     The `oddp' predicate tests to see whether INTEGER is odd, and
     returns `t' if so, `nil' otherwise.  INTEGER must be an integer.

 -- Function: evenp integer
     The `evenp' predicate tests to see whether INTEGER is even, and
     returns `t' if so, `nil' otherwise.  INTEGER must be an integer.

 -- 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: fixnump object
     The `' predicate tests to see whether its argument is an integer
     represented as a fixnum, and returns `t' if so, `nil' otherwise.

 -- Function: bignump object
     The `bignump' predicate tests to see whether OBJECT is an integer
     represented as a bignum, and returns `t' if so, `nil' otherwise.

 -- Function: rationalp object
     The `rationalp' predicate tests to see whether OBJECT is a
     rational number, and returns `t' if so, `nil' otherwise.

 -- Function: ratiop object
     The `ratiop' predicate tests to see whether OBJECT is a number
     represented as a ratio, and returns `t' if so, `nil' otherwise.

 -- Function: floatingp object
     The `floatingp' predicate tests to see whether OBJECT is a
     floating point number represented as a float or a bigfloat, and
     returns `t' if so, `nil' otherwise.

 -- 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.  If the
     bignum extension is present, it returns `nil' for a bigfloat.

 -- Function: bigfloatp object
     The `bigfloatp' predicate tests to see whether OBJECT is an
     floating point number represented as a bigfloat, and returns `t' if
     so, `nil' otherwise.


File: lispref.info,  Node: Comparison of Numbers,  Next: Numeric Conversions,  Prev: Predicates on Numbers,  Up: Numbers

9.6 Comparison of Numbers
=========================

To test numbers for numerical equality, you should normally use `=',
not `eq'.  There can be many distinct floating point, bignum, and ratio
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.

   In versions before 21.5.18, each integer value had a unique Lisp
object in XEmacs Lisp.  Therefore, `eq' was equivalent to `=' where
integers are concerned.  Even with the introduction of bignums, 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 exact
values, because two bignums or ratios with the same value will often
not be the same object.

   On the other hand, some functions, such as the string- and
buffer-searching functions, will return an integer on success, but
something else (usually `nil') on failure.  If it is known what the
numerical subtype (float, bigfloat, or exact) of the returned object
will be if it is a number, then the predicate `eql' can be used for
comparison without signaling an error on some expected return values.
Because of canonicalization, `eql' can be used to compare a fixnum
value to something that might be a ratio; if the potential ratio value
is representable as a fixnum, it will be canonicalized to fixnum before
comparing.  However, although floats and bigfloats are of different
types for the purpose of comparisons via `eql', two bigfloats of
different _precision_ that are `=' will always be `eql'.

     (eql 2 (string-match "ere" "there"))
         => t

     (eql 2 (string-match "ere" "three"))
         => nil

     (eql 2 2.0)
         => nil

     (= 2 (string-match "ere" "there"))
         => t

     (= 2 (string-match "ere" "three"))
         error--> Wrong type argument: number-char-or-marker-p, nil

     (= 2 2.0)
         => t

   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


File: lispref.info,  Node: Numeric Conversions,  Next: Arithmetic Operations,  Prev: Comparison of Numbers,  Up: Numbers

9.7 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.


File: lispref.info,  Node: Arithmetic Operations,  Next: Rounding Operations,  Prev: Numeric Conversions,  Up: Numbers

9.8 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::.


File: lispref.info,  Node: Rounding Operations,  Next: Bitwise Operations,  Prev: Arithmetic Operations,  Up: Numbers

9.9 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.


File: lispref.info,  Node: Bitwise Operations,  Next: Math Functions,  Prev: Rounding Operations,  Up: Numbers

9.10 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


File: lispref.info,  Node: Math Functions,  Next: Random Numbers,  Prev: Bitwise Operations,  Up: Numbers

9.11 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.


File: lispref.info,  Node: Random Numbers,  Prev: Math Functions,  Up: Numbers

9.12 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 reasonably 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.  (This is not cryptographically
strong, it's just hard for a _human_ to anticipate.)

 -- 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.

   The range of random is implementation-dependent.  On any machine, the
result of `(random)' is an arbitrary fixnum, so on 32-bit architectures
it is normally in the range -2^30 (inclusive) to +2^30 (exclusive).
With the optional integer argument LIMIT, the result is in the range 0
(inclusive) to LIMIT (exclusive).  Note this is regardless of the
presence of the bignum extension.


File: lispref.info,  Node: Strings and Characters,  Next: Lists,  Prev: Numbers,  Up: Top

10 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.


File: lispref.info,  Node: String Basics,  Next: Predicates for Strings,  Up: Strings and Characters

10.1 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.


File: lispref.info,  Node: Predicates for Strings,  Next: Creating Strings,  Prev: String Basics,  Up: Strings and Characters

10.2 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.


File: lispref.info,  Node: Creating Strings,  Next: Predicates for Characters,  Prev: Predicates for Strings,  Up: Strings and Characters

10.3 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::.

   The function `split-string', in *Note Regexp Search::, generates a
list of strings by splitting a string on occurances of a regular
expression.


File: lispref.info,  Node: Predicates for Characters,  Next: Character Codes,  Prev: Creating Strings,  Up: Strings and Characters

10.4 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.


File: lispref.info,  Node: Character Codes,  Next: Text Comparison,  Prev: Predicates for Characters,  Up: Strings and Characters

10.5 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.


File: lispref.info,  Node: Text Comparison,  Next: String Conversion,  Prev: Character Codes,  Up: Strings and Characters

10.6 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::.


File: lispref.info,  Node: String Conversion,  Next: Modifying Strings,  Prev: Text Comparison,  Up: Strings and Characters

10.7 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.


File: lispref.info,  Node: Modifying Strings,  Next: String Properties,  Prev: String Conversion,  Up: Strings and Characters

10.8 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'.


File: lispref.info,  Node: String Properties,  Next: Formatting Strings,  Prev: Modifying Strings,  Up: Strings and Characters

10.9 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.

